Add an off switch for agent messages (global, per agent, per workspace)

CLI/CMUXCLI+AgentMessageSettings.swift

@@ -0,0 +1,109 @@
+import Foundation
+
+/// `cmux agent messages [on|off|status] [<target>] [--workspace]`: turns agent
+/// messages off or on for one surface or workspace through
+/// `agent.message.settings`. The app-wide switch is `agentMessages.enabled`.
+extension CMUXCLI {
+    static var agentMessagesHelp: String {
+        String(localized: "cli.help.agentMessages", defaultValue: """
+        Usage: cmux agent messages [on|off|status] [<target>] [--workspace] [--json]
+
+        Turn agent messages off or on for one agent, or show whether it gets
+        them. Turning messages off for an agent refuses new messages to it and
+        marks the ones already queued for it as failed.
+
+        <target> is resolved like cmux agent message: a workspace or surface id
+        or ref, or a workspace title. Without one, the command applies to the
+        surface it runs in. --workspace applies to every surface in the
+        workspace instead.
+
+        Without --workspace, a workspace target means the one agent surface it
+        resolves to now. That surface stays off even if a different surface
+        becomes the workspace's agent later.
+
+        To turn agent messages off everywhere, set agentMessages.enabled to
+        false in ~/.config/cmux/cmux.json or turn off Settings > Automation >
+        Agent Messages.
+
+        Examples:
+          cmux agent messages off
+          cmux agent messages on workspace:3
+          cmux agent messages off --workspace cmux-remote-status
+        """)
+    }
+
+    /// Per-verb help for `cmux agent <verb> --help`, or `nil` for verbs that
+    /// use the `cmux agent` family text.
+    static func agentSubcommandHelp(_ verb: String?) -> String? {
+        switch verb?.lowercased() {
+        case "message", "msg": return agentMessageHelp
+        case "inbox": return agentInboxHelp
+        case "messages": return agentMessagesHelp
+        default: return nil
+        }
+    }
+
+    /// Parsed `cmux agent messages` arguments.
+    struct AgentMessagesSettingArguments: Equatable {
+        /// `nil` reads the current setting.
+        var enabled: Bool?
+        var target: String?
+        var workspace: Bool
+    }
+
+    static func parseAgentMessagesSettingArguments(_ args: [String]) throws -> AgentMessagesSettingArguments {
+        var parsed = AgentMessagesSettingArguments(enabled: nil, target: nil, workspace: false)
+        var words: [String] = []
+        for arg in args {
+            switch arg {
+            case "--json": continue
+            case "--workspace": parsed.workspace = true
+            default:
+                guard !arg.hasPrefix("--") else { throw CLIError(message: agentMessagesHelp) }
+                words.append(arg)
+            }
+        }
+        if let verb = words.first?.lowercased(), ["on", "off", "status"].contains(verb) {
+            parsed.enabled = verb == "status" ? nil : verb == "on"
+            words.removeFirst()
+        }
+        guard words.count <= 1 else { throw CLIError(message: agentMessagesHelp) }
+        parsed.target = words.first
+        return parsed
+    }
+
+    func runAgentMessagesSetting(_ args: [String], client: SocketClient, jsonOutput: Bool) throws {
+        let parsed = try Self.parseAgentMessagesSettingArguments(args)
+        var params: [String: Any] = ["scope": parsed.workspace ? "workspace" : "surface"]
+        if let enabled = parsed.enabled { params["enabled"] = enabled }
+        if let target = parsed.target { params["target"] = target }
+        let env = ProcessInfo.processInfo.environment
+        if let surface = env["CMUX_SURFACE_ID"], !surface.isEmpty { params["surface_id"] = surface }
+        if let workspace = env["CMUX_WORKSPACE_ID"], !workspace.isEmpty { params["workspace_id"] = workspace }
+
+        let payload = try client.sendV2(method: "agent.message.settings", params: params)
+        if jsonOutput {
+            print(jsonString(payload))
+            return
+        }
+        let ref = payload["ref"] as? String ?? "?"
+        let title = payload["workspace_title"] as? String ?? ""
+        let label = title.isEmpty ? ref : "\(ref) (\(title))"
+        let format = payload["receiving"] as? Bool == false
+            ? String(localized: "cli.agentMessages.off", defaultValue: "Messages to %@ are off.")
+            : String(localized: "cli.agentMessages.on", defaultValue: "Messages to %@ are on.")
+        print(String(format: format, label))
+        if payload["workspace_receiving"] as? Bool == false {
+            print(String(
+                localized: "cli.agentMessages.workspaceOff",
+                defaultValue: "Its workspace has messages off, so it receives none."
+            ))
+        }
+        if payload["messages_enabled"] as? Bool == false {
+            print(String(
+                localized: "cli.agentMessages.globalOff",
+                defaultValue: "Agent messages are turned off for all of cmux (agentMessages.enabled is false)."
+            ))
+        }
+    }
+}

CLI/CMUXCLI+AgentMessages.swift

@@ -25,14 +25,14 @@ extension CMUXCLI {
 
     static var agentInboxHelp: String {
         String(localized: "cli.help.agentInbox", defaultValue: """
-        Usage: cmux agent inbox [--surface <target>] [--state queued|delivered|read] [--limit <n>] [--mark-read] [--json]
+        Usage: cmux agent inbox [--surface <target>] [--state queued|delivered|read|failed] [--limit <n>] [--mark-read] [--json]
 
         List agent messages, newest first. Without --surface, lists messages for
         every surface. --mark-read marks the listed messages read.
         """)
     }
 
-    /// Handles `cmux agent message|inbox`. Returns false for other `agent`
+    /// Handles `cmux agent message|inbox|messages`. Returns false for other `agent`
     /// subcommands, which stay aliases of `cmux vm agent`.
     func runAgentMessageCommandIfMatched(
         commandArgs: [String],
@@ -56,6 +56,13 @@ extension CMUXCLI {
             }
             try runAgentInbox(rest, client: client, jsonOutput: jsonOutput)
             return true
+        case "messages":
+            if Self.agentMessageRequestsHelp(rest) {
+                print(Self.agentMessagesHelp)
+                return true
+            }
+            try runAgentMessagesSetting(rest, client: client, jsonOutput: jsonOutput)
+            return true
         default:
             return false
         }

CLI/CMUXCLI+TaskHelp.swift

@@ -204,6 +204,7 @@ extension CMUXCLI {
         \(String(localized: "cli.help.agents.message", defaultValue: "agent message <target> [--from <name>] <text|->"))
         \(String(localized: "cli.help.agents.reply", defaultValue: "agent message --reply-to <id> [--from <name>] <text|->"))
         \(String(localized: "cli.help.agents.inbox", defaultValue: "agent inbox [--surface <target>] [--state <state>] [--mark-read]"))
+        \(String(localized: "cli.help.agents.messages", defaultValue: "agent messages [on|off|status] [<target>] [--workspace]"))
         agent-hibernation <on|off>
         agent-hibernation <hibernate|wake> <surface>
         claude-teams [claude-args...]

CLI/cmux.swift

@@ -5659,7 +5659,7 @@ struct CMUXCLI {
             }
 
         case "agent":
-            // `agent message` and `agent inbox` are local agent messaging;
+            // `agent message`, `inbox` and `messages` are local agent messaging;
             // hibernate and wake act on local agents; everything else stays an
             // alias of `cmux vm agent`.
             if try !runAgentMessageCommandIfMatched(commandArgs: commandArgs, client: client, jsonOutput: jsonOutput) {
@@ -21177,17 +21177,9 @@ struct CMUXCLI {
             print(verbText)
             return true
         }
-        if command == "agent", let verb = commandArgs.first?.lowercased() {
-            switch verb {
-            case "message", "msg":
-                print(Self.agentMessageHelp)
-                return true
-            case "inbox":
-                print(Self.agentInboxHelp)
-                return true
-            default:
-                break
-            }
+        if command == "agent", let text = Self.agentSubcommandHelp(commandArgs.first) {
+            print(text)
+            return true
         }
         guard let text = subcommandUsage(command) else { return false }
         print("cmux \(command)")

Packages/macOS/CmuxAgentJournal/Sources/CmuxAgentJournal/AgentMessage.swift

@@ -1,26 +1,33 @@
 public import Foundation
 
 /// Delivery state of one agent message. A message only moves forward through
-/// these states: queued, then delivered, then read.
+/// these states: queued, then delivered, then read. A queued message that
+/// can no longer be delivered moves to failed instead, which is final.
 public enum AgentMessageDeliveryState: String, Codable, Sendable, CaseIterable {
     /// Stored by cmux and not yet handed to the recipient agent.
     case queued
     /// Handed to the recipient agent through one of its hooks.
     case delivered
     /// The recipient finished a turn after delivery, or a human opened it.
     case read
+    /// Never delivered: messages were turned off for the recipient while the
+    /// message waited. ``AgentMessage/failureReason`` says why.
+    case failed
 
     fileprivate var rank: Int {
         switch self {
         case .queued: return 0
         case .delivered: return 1
         case .read: return 2
+        case .failed: return 3
         }
     }
 
-    /// True when moving from `self` to `next` goes forward.
+    /// True when moving from `self` to `next` goes forward. Only a queued
+    /// message can fail: one already shown to its agent stays delivered or read.
     public func canAdvance(to next: AgentMessageDeliveryState) -> Bool {
-        next.rank > rank
+        if next == .failed { return self == .queued }
+        return next.rank > rank
     }
 }
 
@@ -50,6 +57,8 @@ public struct AgentMessage: Codable, Sendable, Equatable, Identifiable {
     /// `claude.wake` or `codex.prompt-submit`.
     public internal(set) var deliveredVia: String?
     public internal(set) var readAt: Date?
+    /// Set when the message failed: an ``AgentMessageBlock/reason`` code.
+    public internal(set) var failureReason: String?
 
     public init(
         id: String,
@@ -65,7 +74,8 @@ public struct AgentMessage: Codable, Sendable, Equatable, Identifiable {
         state: AgentMessageDeliveryState = .queued,
         deliveredAt: Date? = nil,
         deliveredVia: String? = nil,
-        readAt: Date? = nil
+        readAt: Date? = nil,
+        failureReason: String? = nil
     ) {
         self.id = id
         self.threadId = threadId
@@ -81,6 +91,7 @@ public struct AgentMessage: Codable, Sendable, Equatable, Identifiable {
         self.deliveredAt = deliveredAt
         self.deliveredVia = deliveredVia
         self.readAt = readAt
+        self.failureReason = failureReason
     }
 }
 
@@ -116,6 +127,43 @@ public struct AgentMessageDraft: Sendable, Equatable {
     }
 }
 
+/// What a recipient opt-out applies to.
+public enum AgentMessageRecipientScope: String, Codable, Sendable, CaseIterable {
+    /// One surface (the agent running in it).
+    case surface
+    /// Every surface in a workspace.
+    case workspace
+}
+
+/// Why messages to a recipient are turned off.
+public enum AgentMessageBlock: Sendable, Equatable {
+    /// Agent messages are off for the whole app (`agentMessages.enabled`).
+    case messagesDisabled
+    /// The recipient surface turned messages off.
+    case recipientDisabled(surfaceId: String)
+    /// The recipient's workspace turned messages off.
+    case workspaceDisabled(workspaceId: String)
+
+    /// Stable code stored as a failed message's ``AgentMessage/failureReason``.
+    public var reason: String {
+        switch self {
+        case .messagesDisabled: return "messages_disabled"
+        case .recipientDisabled: return "recipient_disabled"
+        case .workspaceDisabled: return "workspace_disabled"
+        }
+    }
+}
+
+/// The store refused a message because messages are turned off for its
+/// recipient. Nothing was stored.
+public struct AgentMessageBlockedError: Error, Equatable, Sendable {
+    public let block: AgentMessageBlock
+
+    public init(block: AgentMessageBlock) {
+        self.block = block
+    }
+}
+
 /// Why a draft was not accepted into the store.
 public enum AgentMessageValidationError: Error, Equatable, Sendable {
     case emptyBody