fix: harden lobster plugin tool (#1152) (thanks @vignesh07)

feat: configurable heartbeat session

CHANGELOG.md

@@ -7,13 +7,16 @@ Docs: https://docs.clawd.bot
 ### Changes
 - Docs: add troubleshooting entry for gateway.mode blocking gateway start. https://docs.clawd.bot/gateway/troubleshooting
 - Onboarding: remove the run setup-token auth option (paste setup-token or reuse CLI creds instead).
+- Signal: add typing indicators and DM read receipts via signal-cli.
 
 ### Fixes
 - Doctor: warn when gateway.mode is unset with configure/config guidance.
+- Lobster: fix plugin discovery and harden the tool runtime. (#1152) Thanks @vignesh07.
 
 ## 2026.1.21
 
 ### Changes
+- Heartbeat: allow running heartbeats in an explicit session key. (#1256) Thanks @zknicker.
 - CLI: default exec approvals to the local host, add gateway/node targeting flags, and show target details in allowlist output.
 - CLI: exec approvals mutations render tables instead of raw JSON.
 - Exec approvals: support wildcard agent allowlists (`*`) across all agents.
@@ -29,6 +32,7 @@ Docs: https://docs.clawd.bot
 ### Fixes
 - Nodes/macOS: prompt on allowlist miss for node exec approvals, persist allowlist decisions, and flatten node invoke errors. (#1394) Thanks @ngutman.
 - Gateway: keep auto bind loopback-first and add explicit tailnet binding to avoid Tailscale taking over local UI. (#1380)
+- Agents: enforce 9-char alphanumeric tool call ids for Mistral providers. (#1372) Thanks @zerone0x.
 - Embedded runner: persist injected history images so attachments aren’t reloaded each turn. (#1374) Thanks @Nicell.
 - Nodes tool: include agent/node/gateway context in tool failure logs to speed approval debugging.
 - macOS: exec approvals now respect wildcard agent allowlists (`*`).

appcast.xml

@@ -3,13 +3,13 @@
     <channel>
         <title>Clawdbot</title>
         <item>
-            <title>2026.1.20</title>
+            <title>2026.1.21</title>
             <pubDate>Wed, 21 Jan 2026 08:18:22 +0000</pubDate>
             <link>https://raw.githubusercontent.com/clawdbot/clawdbot/main/appcast.xml</link>
             <sparkle:version>7116</sparkle:version>
-            <sparkle:shortVersionString>2026.1.20</sparkle:shortVersionString>
+            <sparkle:shortVersionString>2026.1.21</sparkle:shortVersionString>
             <sparkle:minimumSystemVersion>15.0</sparkle:minimumSystemVersion>
-            <description><![CDATA[<h2>Clawdbot 2026.1.20</h2>
+            <description><![CDATA[<h2>Clawdbot 2026.1.21</h2>
 <h3>Changes</h3>
 <ul>
 <li>Control UI: add copy-as-markdown with error feedback. (#1345) https://docs.clawd.bot/web/control-ui</li>
@@ -190,7 +190,7 @@
 Thanks @AlexMikhalev, @CoreyH, @John-Rood, @KrauseFx, @MaudeBot, @Nachx639, @NicholaiVogel, @RyanLisse, @ThePickle31, @VACInc, @Whoaa512, @YuriNachos, @aaronveklabs, @abdaraxus, @alauppe, @ameno-, @artuskg, @austinm911, @bradleypriest, @cheeeee, @dougvk, @fogboots, @gnarco, @gumadeiras, @jdrhyne, @joelklabo, @longmaba, @mukhtharcm, @odysseus0, @oscargavin, @rhjoh, @sebslight, @sibbl, @sleontenko, @steipete, @suminhthanh, @thewilloftheshadow, @tyler6204, @vignesh07, @visionik, @ysqander, @zerone0x.
 <p><a href="https://github.com/clawdbot/clawdbot/blob/main/CHANGELOG.md">View full changelog</a></p>
 ]]></description>
-            <enclosure url="https://github.com/clawdbot/clawdbot/releases/download/v2026.1.20/Clawdbot-2026.1.20.zip" length="12208102" type="application/octet-stream" sparkle:edSignature="hU495Eii8O3qmmUnxYFhXyEGv+qan6KL+GpeuBhPIXf+7B5F/gBh5Oz9cHaqaAPoZ4/3Bo6xgvic0HTkbz6gDw=="/>
+            <enclosure url="https://github.com/clawdbot/clawdbot/releases/download/v2026.1.21/Clawdbot-2026.1.21.zip" length="12208102" type="application/octet-stream" sparkle:edSignature="hU495Eii8O3qmmUnxYFhXyEGv+qan6KL+GpeuBhPIXf+7B5F/gBh5Oz9cHaqaAPoZ4/3Bo6xgvic0HTkbz6gDw=="/>
         </item>
         <item>
             <title>2026.1.16-2</title>
@@ -290,4 +290,4 @@ Thanks @AlexMikhalev, @CoreyH, @John-Rood, @KrauseFx, @MaudeBot, @Nachx639, @Nic
             <enclosure url="https://github.com/clawdbot/clawdbot/releases/download/v2026.1.15/Clawdbot-2026.1.15.zip" length="12127276" type="application/octet-stream" sparkle:edSignature="o79vwTbtW/d91NQFRVfUDhsv6D4zIw7IkhY0N1iLImMu94BURgLcecA6z7Smy3bMobPwOyzN8yfm6mA/Rt8FCA=="/>
         </item>
     </channel>
-</rss>
+</rss>

apps/android/app/build.gradle.kts

@@ -21,8 +21,8 @@ android {
     applicationId = "com.clawdbot.android"
     minSdk = 31
     targetSdk = 36
-    versionCode = 202601200
-    versionName = "2026.1.20"
+    versionCode = 202601210
+    versionName = "2026.1.21"
   }
 
   buildTypes {

apps/ios/Sources/Info.plist

@@ -19,9 +19,9 @@
 	<key>CFBundlePackageType</key>
 	<string>APPL</string>
 	<key>CFBundleShortVersionString</key>
-	<string>2026.1.20</string>
+	<string>2026.1.21</string>
 	<key>CFBundleVersion</key>
-	<string>20260120</string>
+	<string>20260121</string>
 	<key>NSAppTransportSecurity</key>
 	<dict>
 		<key>NSAllowsArbitraryLoadsInWebContent</key>

apps/ios/Tests/Info.plist

@@ -17,8 +17,8 @@
 	<key>CFBundlePackageType</key>
 	<string>BNDL</string>
 	<key>CFBundleShortVersionString</key>
-	<string>2026.1.20</string>
+	<string>2026.1.21</string>
 	<key>CFBundleVersion</key>
-	<string>20260120</string>
+	<string>20260121</string>
 </dict>
 </plist>

apps/ios/project.yml

@@ -81,8 +81,8 @@ targets:
       properties:
         CFBundleDisplayName: Clawdbot
         CFBundleIconName: AppIcon
-        CFBundleShortVersionString: "2026.1.20"
-        CFBundleVersion: "20260120"
+        CFBundleShortVersionString: "2026.1.21"
+        CFBundleVersion: "20260121"
         UILaunchScreen: {}
         UIApplicationSceneManifest:
           UIApplicationSupportsMultipleScenes: false
@@ -130,5 +130,5 @@ targets:
       path: Tests/Info.plist
       properties:
         CFBundleDisplayName: ClawdbotTests
-        CFBundleShortVersionString: "2026.1.20"
-        CFBundleVersion: "20260120"
+        CFBundleShortVersionString: "2026.1.21"
+        CFBundleVersion: "20260121"

apps/macos/Sources/Clawdbot/ConnectionModeCoordinator.swift

@@ -6,15 +6,20 @@ final class ConnectionModeCoordinator {
     static let shared = ConnectionModeCoordinator()
 
     private let logger = Logger(subsystem: "com.clawdbot", category: "connection")
+    private var lastMode: AppState.ConnectionMode?
 
     /// Apply the requested connection mode by starting/stopping local gateway,
     /// managing the control-channel SSH tunnel, and cleaning up chat windows/panels.
     func apply(mode: AppState.ConnectionMode, paused: Bool) async {
+        if let lastMode = self.lastMode, lastMode != mode {
+            GatewayProcessManager.shared.clearLastFailure()
+            NodesStore.shared.lastError = nil
+        }
+        self.lastMode = mode
         switch mode {
         case .unconfigured:
-            if let error = await NodeServiceManager.stop() {
-                NodesStore.shared.lastError = "Node service stop failed: \(error)"
-            }
+            _ = await NodeServiceManager.stop()
+            NodesStore.shared.lastError = nil
             await RemoteTunnelManager.shared.stopAll()
             WebChatManager.shared.resetTunnels()
             GatewayProcessManager.shared.stop()
@@ -23,9 +28,8 @@ final class ConnectionModeCoordinator {
             Task.detached { await PortGuardian.shared.sweep(mode: .unconfigured) }
 
         case .local:
-            if let error = await NodeServiceManager.stop() {
-                NodesStore.shared.lastError = "Node service stop failed: \(error)"
-            }
+            _ = await NodeServiceManager.stop()
+            NodesStore.shared.lastError = nil
             await RemoteTunnelManager.shared.stopAll()
             WebChatManager.shared.resetTunnels()
             let shouldStart = GatewayAutostartPolicy.shouldStartGateway(mode: .local, paused: paused)
@@ -56,6 +60,7 @@ final class ConnectionModeCoordinator {
             WebChatManager.shared.resetTunnels()
 
             do {
+                NodesStore.shared.lastError = nil
                 if let error = await NodeServiceManager.start() {
                     NodesStore.shared.lastError = "Node service start failed: \(error)"
                 }

apps/macos/Sources/Clawdbot/ExecApprovals.swift

@@ -280,8 +280,10 @@ enum ExecApprovalsStore {
         let resolvedAgent = ExecApprovalsResolvedDefaults(
             security: agentEntry.security ?? wildcardEntry.security ?? resolvedDefaults.security,
             ask: agentEntry.ask ?? wildcardEntry.ask ?? resolvedDefaults.ask,
-            askFallback: agentEntry.askFallback ?? wildcardEntry.askFallback ?? resolvedDefaults.askFallback,
-            autoAllowSkills: agentEntry.autoAllowSkills ?? wildcardEntry.autoAllowSkills ?? resolvedDefaults.autoAllowSkills)
+            askFallback: agentEntry.askFallback ?? wildcardEntry.askFallback
+                ?? resolvedDefaults.askFallback,
+            autoAllowSkills: agentEntry.autoAllowSkills ?? wildcardEntry.autoAllowSkills
+                ?? resolvedDefaults.autoAllowSkills)
         let allowlist = ((wildcardEntry.allowlist ?? []) + (agentEntry.allowlist ?? []))
             .map { entry in
                 ExecAllowlistEntry(

apps/macos/Sources/Clawdbot/GatewayProcessManager.swift

@@ -42,10 +42,20 @@ final class GatewayProcessManager {
     private var environmentRefreshTask: Task<Void, Never>?
     private var lastEnvironmentRefresh: Date?
     private var logRefreshTask: Task<Void, Never>?
+    #if DEBUG
+    private var testingConnection: GatewayConnection?
+    #endif
     private let logger = Logger(subsystem: "com.clawdbot", category: "gateway.process")
 
     private let logLimit = 20000 // characters to keep in-memory
     private let environmentRefreshMinInterval: TimeInterval = 30
+    private var connection: GatewayConnection {
+        #if DEBUG
+        return self.testingConnection ?? .shared
+        #else
+        return .shared
+        #endif
+    }
 
     func setActive(_ active: Bool) {
         // Remote mode should never spawn a local gateway; treat as stopped.
@@ -126,6 +136,10 @@ final class GatewayProcessManager {
         }
     }
 
+    func clearLastFailure() {
+        self.lastFailureReason = nil
+    }
+
     func refreshEnvironmentStatus(force: Bool = false) {
         let now = Date()
         if !force {
@@ -178,7 +192,7 @@ final class GatewayProcessManager {
         let hasListener = instance != nil
 
         let attemptAttach = {
-            try await GatewayConnection.shared.requestRaw(method: .health, timeoutMs: 2000)
+            try await self.connection.requestRaw(method: .health, timeoutMs: 2000)
         }
 
         for attempt in 0..<(hasListener ? 3 : 1) {
@@ -187,6 +201,7 @@ final class GatewayProcessManager {
                 let snap = decodeHealthSnapshot(from: data)
                 let details = self.describe(details: instanceText, port: port, snap: snap)
                 self.existingGatewayDetails = details
+                self.clearLastFailure()
                 self.status = .attachedExisting(details: details)
                 self.appendLog("[gateway] using existing instance: \(details)\n")
                 self.logger.info("gateway using existing instance details=\(details)")
@@ -310,9 +325,10 @@ final class GatewayProcessManager {
         while Date() < deadline {
             if !self.desiredActive { return }
             do {
-                _ = try await GatewayConnection.shared.requestRaw(method: .health, timeoutMs: 1500)
+                _ = try await self.connection.requestRaw(method: .health, timeoutMs: 1500)
                 let instance = await PortGuardian.shared.describe(port: port)
                 let details = instance.map { "pid \($0.pid)" }
+                self.clearLastFailure()
                 self.status = .running(details: details)
                 self.logger.info("gateway started details=\(details ?? "ok")")
                 self.refreshControlChannelIfNeeded(reason: "gateway started")
@@ -352,7 +368,8 @@ final class GatewayProcessManager {
         while Date() < deadline {
             if !self.desiredActive { return false }
             do {
-                _ = try await GatewayConnection.shared.requestRaw(method: .health, timeoutMs: 1500)
+                _ = try await self.connection.requestRaw(method: .health, timeoutMs: 1500)
+                self.clearLastFailure()
                 return true
             } catch {
                 try? await Task.sleep(nanoseconds: 300_000_000)
@@ -385,3 +402,19 @@ final class GatewayProcessManager {
         return String(text.suffix(limit))
     }
 }
+
+#if DEBUG
+extension GatewayProcessManager {
+    func setTestingConnection(_ connection: GatewayConnection?) {
+        self.testingConnection = connection
+    }
+
+    func setTestingDesiredActive(_ active: Bool) {
+        self.desiredActive = active
+    }
+
+    func setTestingLastFailureReason(_ reason: String?) {
+        self.lastFailureReason = reason
+    }
+}
+#endif

apps/macos/Sources/Clawdbot/GeneralSettings.swift

@@ -191,7 +191,6 @@ struct GeneralSettings: View {
             if self.state.connectionMode == .remote {
                 self.remoteCard
             }
-
         }
     }
 

apps/macos/Sources/Clawdbot/NodeMode/MacNodeRuntime.swift

@@ -480,62 +480,22 @@ actor MacNodeRuntime {
                 message: "SYSTEM_RUN_DISABLED: security=deny")
         }
 
-        let requiresAsk = ExecApprovalHelpers.requiresAsk(
-            ask: ask,
-            security: security,
-            allowlistMatch: allowlistMatch,
-            skillAllow: skillAllow)
-
-        let decisionFromParams = ExecApprovalHelpers.parseDecision(params.approvalDecision)
-        var approvedByAsk = params.approved == true || decisionFromParams != nil
-        var persistAllowlist = decisionFromParams == .allowAlways
-        if decisionFromParams == .deny {
-            await self.emitExecEvent(
-                "exec.denied",
-                payload: ExecEventPayload(
-                    sessionKey: sessionKey,
-                    runId: runId,
-                    host: "node",
-                    command: displayCommand,
-                    reason: "user-denied"))
-            return Self.errorResponse(
-                req,
-                code: .unavailable,
-                message: "SYSTEM_RUN_DENIED: user denied")
-        }
-        if requiresAsk, !approvedByAsk {
-            let decision = await MainActor.run {
-                ExecApprovalsPromptPresenter.prompt(
-                    ExecApprovalPromptRequest(
-                        command: displayCommand,
-                        cwd: params.cwd,
-                        host: "node",
-                        security: security.rawValue,
-                        ask: ask.rawValue,
-                        agentId: agentId,
-                        resolvedPath: resolution?.resolvedPath))
-            }
-            switch decision {
-            case .deny:
-                await self.emitExecEvent(
-                    "exec.denied",
-                    payload: ExecEventPayload(
-                        sessionKey: sessionKey,
-                        runId: runId,
-                        host: "node",
-                        command: displayCommand,
-                        reason: "user-denied"))
-                return Self.errorResponse(
-                    req,
-                    code: .unavailable,
-                    message: "SYSTEM_RUN_DENIED: user denied")
-            case .allowAlways:
-                approvedByAsk = true
-                persistAllowlist = true
-            case .allowOnce:
-                approvedByAsk = true
-            }
-        }
+        let approval = await self.resolveSystemRunApproval(
+            req: req,
+            params: params,
+            context: ExecRunContext(
+                displayCommand: displayCommand,
+                security: security,
+                ask: ask,
+                agentId: agentId,
+                resolution: resolution,
+                allowlistMatch: allowlistMatch,
+                skillAllow: skillAllow,
+                sessionKey: sessionKey,
+                runId: runId))
+        if let response = approval.response { return response }
+        let approvedByAsk = approval.approvedByAsk
+        let persistAllowlist = approval.persistAllowlist
         if persistAllowlist, security == .allowlist,
            let pattern = ExecApprovalHelpers.allowlistPattern(command: command, resolution: resolution)
         {
@@ -659,6 +619,99 @@ actor MacNodeRuntime {
         return BridgeInvokeResponse(id: req.id, ok: true, payloadJSON: payload)
     }
 
+    private struct ExecApprovalOutcome {
+        var approvedByAsk: Bool
+        var persistAllowlist: Bool
+        var response: BridgeInvokeResponse?
+    }
+
+    private struct ExecRunContext {
+        var displayCommand: String
+        var security: ExecSecurity
+        var ask: ExecAsk
+        var agentId: String?
+        var resolution: ExecCommandResolution?
+        var allowlistMatch: ExecAllowlistEntry?
+        var skillAllow: Bool
+        var sessionKey: String
+        var runId: String
+    }
+
+    private func resolveSystemRunApproval(
+        req: BridgeInvokeRequest,
+        params: ClawdbotSystemRunParams,
+        context: ExecRunContext) async -> ExecApprovalOutcome
+    {
+        let requiresAsk = ExecApprovalHelpers.requiresAsk(
+            ask: context.ask,
+            security: context.security,
+            allowlistMatch: context.allowlistMatch,
+            skillAllow: context.skillAllow)
+
+        let decisionFromParams = ExecApprovalHelpers.parseDecision(params.approvalDecision)
+        var approvedByAsk = params.approved == true || decisionFromParams != nil
+        var persistAllowlist = decisionFromParams == .allowAlways
+        if decisionFromParams == .deny {
+            await self.emitExecEvent(
+                "exec.denied",
+                payload: ExecEventPayload(
+                    sessionKey: context.sessionKey,
+                    runId: context.runId,
+                    host: "node",
+                    command: context.displayCommand,
+                    reason: "user-denied"))
+            return ExecApprovalOutcome(
+                approvedByAsk: approvedByAsk,
+                persistAllowlist: persistAllowlist,
+                response: Self.errorResponse(
+                    req,
+                    code: .unavailable,
+                    message: "SYSTEM_RUN_DENIED: user denied"))
+        }
+
+        if requiresAsk, !approvedByAsk {
+            let decision = await MainActor.run {
+                ExecApprovalsPromptPresenter.prompt(
+                    ExecApprovalPromptRequest(
+                        command: context.displayCommand,
+                        cwd: params.cwd,
+                        host: "node",
+                        security: context.security.rawValue,
+                        ask: context.ask.rawValue,
+                        agentId: context.agentId,
+                        resolvedPath: context.resolution?.resolvedPath))
+            }
+            switch decision {
+            case .deny:
+                await self.emitExecEvent(
+                    "exec.denied",
+                    payload: ExecEventPayload(
+                        sessionKey: context.sessionKey,
+                        runId: context.runId,
+                        host: "node",
+                        command: context.displayCommand,
+                        reason: "user-denied"))
+                return ExecApprovalOutcome(
+                    approvedByAsk: approvedByAsk,
+                    persistAllowlist: persistAllowlist,
+                    response: Self.errorResponse(
+                        req,
+                        code: .unavailable,
+                        message: "SYSTEM_RUN_DENIED: user denied"))
+            case .allowAlways:
+                approvedByAsk = true
+                persistAllowlist = true
+            case .allowOnce:
+                approvedByAsk = true
+            }
+        }
+
+        return ExecApprovalOutcome(
+            approvedByAsk: approvedByAsk,
+            persistAllowlist: persistAllowlist,
+            response: nil)
+    }
+
     private func handleSystemExecApprovalsGet(_ req: BridgeInvokeRequest) async throws -> BridgeInvokeResponse {
         _ = ExecApprovalsStore.ensureFile()
         let snapshot = ExecApprovalsStore.readSnapshot()

apps/macos/Sources/Clawdbot/PermissionsSettings.swift

@@ -47,7 +47,6 @@ struct PermissionStatusList: View {
             .font(.footnote)
             .padding(.top, 2)
             .help("Refresh status")
-
         }
     }
 

apps/macos/Sources/Clawdbot/Resources/Info.plist

@@ -15,9 +15,9 @@
     <key>CFBundlePackageType</key>
     <string>APPL</string>
     <key>CFBundleShortVersionString</key>
-    <string>2026.1.20</string>
+    <string>2026.1.21</string>
     <key>CFBundleVersion</key>
-    <string>202601200</string>
+    <string>202601210</string>
     <key>CFBundleIconFile</key>
     <string>Clawdbot</string>
     <key>CFBundleURLTypes</key>

apps/macos/Sources/Clawdbot/TailscaleService.swift

@@ -221,6 +221,6 @@ final class TailscaleService {
     }
 
     nonisolated static func fallbackTailnetIPv4() -> String? {
-        Self.detectTailnetIPv4()
+        self.detectTailnetIPv4()
     }
 }

apps/macos/Sources/ClawdbotProtocol/GatewayModels.swift

@@ -1908,6 +1908,7 @@ public struct ExecApprovalsSnapshot: Codable, Sendable {
 }
 
 public struct ExecApprovalRequestParams: Codable, Sendable {
+    public let id: String?
     public let command: String
     public let cwd: String?
     public let host: String?
@@ -1919,6 +1920,7 @@ public struct ExecApprovalRequestParams: Codable, Sendable {
     public let timeoutms: Int?
 
     public init(
+        id: String?,
         command: String,
         cwd: String?,
         host: String?,
@@ -1929,6 +1931,7 @@ public struct ExecApprovalRequestParams: Codable, Sendable {
         sessionkey: String?,
         timeoutms: Int?
     ) {
+        self.id = id
         self.command = command
         self.cwd = cwd
         self.host = host
@@ -1940,6 +1943,7 @@ public struct ExecApprovalRequestParams: Codable, Sendable {
         self.timeoutms = timeoutms
     }
     private enum CodingKeys: String, CodingKey {
+        case id
         case command
         case cwd
         case host

apps/macos/Tests/ClawdbotIPCTests/GatewayEnvironmentTests.swift

@@ -48,7 +48,10 @@ import Testing
 
     @Test func expectedGatewayVersionFromStringUsesParser() {
         #expect(GatewayEnvironment.expectedGatewayVersion(from: "v9.1.2") == Semver(major: 9, minor: 1, patch: 2))
-        #expect(GatewayEnvironment.expectedGatewayVersion(from: "2026.1.11-4") == Semver(major: 2026, minor: 1, patch: 11))
+        #expect(GatewayEnvironment.expectedGatewayVersion(from: "2026.1.11-4") == Semver(
+            major: 2026,
+            minor: 1,
+            patch: 11))
         #expect(GatewayEnvironment.expectedGatewayVersion(from: nil) == nil)
     }
 }

apps/macos/Tests/ClawdbotIPCTests/GatewayProcessManagerTests.swift

@@ -0,0 +1,146 @@
+import Foundation
+import os
+import Testing
+@testable import Clawdbot
+
+@Suite(.serialized)
+@MainActor
+struct GatewayProcessManagerTests {
+    private final class FakeWebSocketTask: WebSocketTasking, @unchecked Sendable {
+        private let connectRequestID = OSAllocatedUnfairLock<String?>(initialState: nil)
+        private let pendingReceiveHandler =
+            OSAllocatedUnfairLock<(@Sendable (Result<URLSessionWebSocketTask.Message, Error>)
+                    -> Void)?>(initialState: nil)
+        private let cancelCount = OSAllocatedUnfairLock(initialState: 0)
+        private let sendCount = OSAllocatedUnfairLock(initialState: 0)
+
+        var state: URLSessionTask.State = .suspended
+
+        func resume() {
+            self.state = .running
+        }
+
+        func cancel(with closeCode: URLSessionWebSocketTask.CloseCode, reason: Data?) {
+            _ = (closeCode, reason)
+            self.state = .canceling
+            self.cancelCount.withLock { $0 += 1 }
+            let handler = self.pendingReceiveHandler.withLock { handler in
+                defer { handler = nil }
+                return handler
+            }
+            handler?(Result<URLSessionWebSocketTask.Message, Error>.failure(URLError(.cancelled)))
+        }
+
+        func send(_ message: URLSessionWebSocketTask.Message) async throws {
+            let currentSendCount = self.sendCount.withLock { count in
+                defer { count += 1 }
+                return count
+            }
+
+            if currentSendCount == 0 {
+                guard case let .data(data) = message else { return }
+                if let obj = try? JSONSerialization.jsonObject(with: data) as? [String: Any],
+                   (obj["type"] as? String) == "req",
+                   (obj["method"] as? String) == "connect",
+                   let id = obj["id"] as? String
+                {
+                    self.connectRequestID.withLock { $0 = id }
+                }
+                return
+            }
+
+            guard case let .data(data) = message else { return }
+            guard
+                let obj = try? JSONSerialization.jsonObject(with: data) as? [String: Any],
+                (obj["type"] as? String) == "req",
+                let id = obj["id"] as? String
+            else {
+                return
+            }
+
+            let response = Self.responseData(id: id)
+            let handler = self.pendingReceiveHandler.withLock { $0 }
+            handler?(Result<URLSessionWebSocketTask.Message, Error>.success(.data(response)))
+        }
+
+        func receive() async throws -> URLSessionWebSocketTask.Message {
+            let id = self.connectRequestID.withLock { $0 } ?? "connect"
+            return .data(Self.connectOkData(id: id))
+        }
+
+        func receive(
+            completionHandler: @escaping @Sendable (Result<URLSessionWebSocketTask.Message, Error>) -> Void)
+        {
+            self.pendingReceiveHandler.withLock { $0 = completionHandler }
+        }
+
+        private static func connectOkData(id: String) -> Data {
+            let json = """
+            {
+              "type": "res",
+              "id": "\(id)",
+              "ok": true,
+              "payload": {
+                "type": "hello-ok",
+                "protocol": 2,
+                "server": { "version": "test", "connId": "test" },
+                "features": { "methods": [], "events": [] },
+                "snapshot": {
+                  "presence": [ { "ts": 1 } ],
+                  "health": {},
+                  "stateVersion": { "presence": 0, "health": 0 },
+                  "uptimeMs": 0
+                },
+                "policy": { "maxPayload": 1, "maxBufferedBytes": 1, "tickIntervalMs": 30000 }
+              }
+            }
+            """
+            return Data(json.utf8)
+        }
+
+        private static func responseData(id: String) -> Data {
+            let json = """
+            {
+              "type": "res",
+              "id": "\(id)",
+              "ok": true,
+              "payload": { "ok": true }
+            }
+            """
+            return Data(json.utf8)
+        }
+    }
+
+    private final class FakeWebSocketSession: WebSocketSessioning, @unchecked Sendable {
+        private let tasks = OSAllocatedUnfairLock(initialState: [FakeWebSocketTask]())
+
+        func makeWebSocketTask(url: URL) -> WebSocketTaskBox {
+            _ = url
+            let task = FakeWebSocketTask()
+            self.tasks.withLock { $0.append(task) }
+            return WebSocketTaskBox(task: task)
+        }
+    }
+
+    @Test func clearsLastFailureWhenHealthSucceeds() async {
+        let session = FakeWebSocketSession()
+        let url = URL(string: "ws://example.invalid")!
+        let connection = GatewayConnection(
+            configProvider: { (url: url, token: nil, password: nil) },
+            sessionBox: WebSocketSessionBox(session: session))
+
+        let manager = GatewayProcessManager.shared
+        manager.setTestingConnection(connection)
+        manager.setTestingDesiredActive(true)
+        manager.setTestingLastFailureReason("health failed")
+        defer {
+            manager.setTestingConnection(nil)
+            manager.setTestingDesiredActive(false)
+            manager.setTestingLastFailureReason(nil)
+        }
+
+        let ready = await manager.waitForGatewayReady(timeout: 0.5)
+        #expect(ready)
+        #expect(manager.lastFailureReason == nil)
+    }
+}

apps/shared/ClawdbotKit/Sources/ClawdbotProtocol/GatewayModels.swift

@@ -1908,6 +1908,7 @@ public struct ExecApprovalsSnapshot: Codable, Sendable {
 }
 
 public struct ExecApprovalRequestParams: Codable, Sendable {
+    public let id: String?
     public let command: String
     public let cwd: String?
     public let host: String?
@@ -1919,6 +1920,7 @@ public struct ExecApprovalRequestParams: Codable, Sendable {
     public let timeoutms: Int?
 
     public init(
+        id: String?,
         command: String,
         cwd: String?,
         host: String?,
@@ -1929,6 +1931,7 @@ public struct ExecApprovalRequestParams: Codable, Sendable {
         sessionkey: String?,
         timeoutms: Int?
     ) {
+        self.id = id
         self.command = command
         self.cwd = cwd
         self.host = host
@@ -1940,6 +1943,7 @@ public struct ExecApprovalRequestParams: Codable, Sendable {
         self.timeoutms = timeoutms
     }
     private enum CodingKeys: String, CodingKey {
+        case id
         case command
         case cwd
         case host

docs/channels/signal.md

@@ -100,6 +100,11 @@ Groups:
 - Use `channels.signal.ignoreAttachments` to skip downloading media.
 - Group history context uses `channels.signal.historyLimit` (or `channels.signal.accounts.*.historyLimit`), falling back to `messages.groupChat.historyLimit`. Set `0` to disable (default 50).
 
+## Typing + read receipts
+- **Typing indicators**: Clawdbot sends typing signals via `signal-cli sendTyping` and refreshes them while a reply is running.
+- **Read receipts**: when `channels.signal.sendReadReceipts` is true, Clawdbot forwards read receipts for allowed DMs.
+- Signal-cli does not expose read receipts for groups.
+
 ## Delivery targets (CLI/cron)
 - DMs: `signal:+15551234567` (or plain E.164).
 - Groups: `signal:group:<groupId>`.

docs/channels/whatsapp.md

@@ -334,6 +334,7 @@ WhatsApp sends audio as **voice notes** (PTT bubble).
 - `agents.defaults.heartbeat.model` (optional override)
 - `agents.defaults.heartbeat.target`
 - `agents.defaults.heartbeat.to`
+- `agents.defaults.heartbeat.session`
 - `agents.list[].heartbeat.*` (per-agent overrides)
 - `session.*` (scope, idle, store, mainKey)
 - `web.enabled` (disable channel startup when false)

docs/docs.json

@@ -977,6 +977,7 @@
           "plugin",
           "plugins/voice-call",
           "plugins/zalouser",
+          "tools/lobster",
           "tools/exec",
           "tools/web",
           "tools/apply-patch",

docs/gateway/bridge-protocol.md

@@ -58,8 +58,8 @@ Exact allowlist is enforced in `src/gateway/server-bridge.ts`.
 
 ## Exec lifecycle events
 
-Nodes can emit `exec.started`, `exec.finished`, or `exec.denied` events to surface
-system.run activity. These are mapped to system events in the gateway.
+Nodes can emit `exec.finished` or `exec.denied` events to surface system.run activity.
+These are mapped to system events in the gateway. (Legacy nodes may still emit `exec.started`.)
 
 Payload fields (all optional unless noted):
 - `sessionKey` (required): agent session to receive the system event.

docs/gateway/configuration.md

@@ -24,7 +24,7 @@ Unknown keys, malformed types, or invalid values cause the Gateway to **refuse t
 
 When validation fails:
 - The Gateway does not boot.
-- Only diagnostic commands are allowed (for example: `clawdbot doctor`, `clawdbot logs`, `clawdbot health`, `clawdbot status`, `clawdbot gateway status`, `clawdbot gateway probe`, `clawdbot help`).
+- Only diagnostic commands are allowed (for example: `clawdbot doctor`, `clawdbot logs`, `clawdbot health`, `clawdbot status`, `clawdbot service`, `clawdbot help`).
 - Run `clawdbot doctor` to see the exact issues.
 - Run `clawdbot doctor --fix` (or `--yes`) to apply migrations/repairs.
 
@@ -1414,7 +1414,7 @@ Each `agents.defaults.models` entry can include:
 - `alias` (optional model shortcut, e.g. `/opus`).
 - `params` (optional provider-specific API params passed through to the model request).
 
-`params` is also applied to streaming runs (embedded agent + compaction). Supported keys today: `temperature`, `maxTokens`, `cacheControlTtl` (`"5m"` or `"1h"`, Anthropic API + OpenRouter Anthropic models only; ignored for Anthropic OAuth/Claude Code tokens). These merge with call-time options; caller-supplied values win. `temperature` is an advanced knob—leave unset unless you know the model’s defaults and need a change. Clawdbot includes the `extended-cache-ttl-2025-04-11` beta flag for Anthropic API; keep it if you override provider headers.
+`params` is also applied to streaming runs (embedded agent + compaction). Supported keys today: `temperature`, `maxTokens`. These merge with call-time options; caller-supplied values win. `temperature` is an advanced knob—leave unset unless you know the model’s defaults and need a change.
 
 Example:
 
@@ -1569,7 +1569,7 @@ Example:
 }
 ```
 
-#### `agents.defaults.contextPruning` (TTL-aware tool-result pruning)
+#### `agents.defaults.contextPruning` (tool-result pruning)
 
 `agents.defaults.contextPruning` prunes **old tool results** from the in-memory context right before a request is sent to the LLM.
 It does **not** modify the session history on disk (`*.jsonl` remains complete).
@@ -1580,9 +1580,11 @@ High level:
 - Never touches user/assistant messages.
 - Protects the last `keepLastAssistants` assistant messages (no tool results after that point are pruned).
 - Protects the bootstrap prefix (nothing before the first user message is pruned).
-- Mode:
-  - `cache-ttl`: pruning only runs when the last Anthropic call for the session is **older** than `ttl`.
-    When it runs, it uses the same soft-trim + hard-clear behavior as before.
+- Modes:
+  - `adaptive`: soft-trims oversized tool results (keep head/tail) when the estimated context ratio crosses `softTrimRatio`.
+    Then hard-clears the oldest eligible tool results when the estimated context ratio crosses `hardClearRatio` **and**
+    there’s enough prunable tool-result bulk (`minPrunableToolChars`).
+  - `aggressive`: always replaces eligible tool results before the cutoff with the `hardClear.placeholder` (no ratio checks).
 
 Soft vs hard pruning (what changes in the context sent to the LLM):
 - **Soft-trim**: only for *oversized* tool results. Keeps the beginning + end and inserts `...` in the middle.
@@ -1596,41 +1598,44 @@ Notes / current limitations:
 - Tool results containing **image blocks are skipped** (never trimmed/cleared) right now.
 - The estimated “context ratio” is based on **characters** (approximate), not exact tokens.
 - If the session doesn’t contain at least `keepLastAssistants` assistant messages yet, pruning is skipped.
-- `cache-ttl` only activates for Anthropic API calls (and OpenRouter Anthropic models).
-- After a prune, the TTL window resets so subsequent requests keep cache until `ttl` expires again.
-- For best results, match `contextPruning.ttl` to the model `cacheControlTtl` you set in `agents.defaults.models.*.params`.
+- In `aggressive` mode, `hardClear.enabled` is ignored (eligible tool results are always replaced with `hardClear.placeholder`).
 
-Default (off, unless Anthropic auth profiles are detected):
+Default (adaptive):
+```json5
+{
+  agents: { defaults: { contextPruning: { mode: "adaptive" } } }
+}
+```
+
+To disable:
 ```json5
 {
   agents: { defaults: { contextPruning: { mode: "off" } } }
 }
 ```
 
-Enable TTL-aware pruning:
+Defaults (when `mode` is `"adaptive"` or `"aggressive"`):
+- `keepLastAssistants`: `3`
+- `softTrimRatio`: `0.3` (adaptive only)
+- `hardClearRatio`: `0.5` (adaptive only)
+- `minPrunableToolChars`: `50000` (adaptive only)
+- `softTrim`: `{ maxChars: 4000, headChars: 1500, tailChars: 1500 }` (adaptive only)
+- `hardClear`: `{ enabled: true, placeholder: "[Old tool result content cleared]" }`
+
+Example (aggressive, minimal):
 ```json5
 {
-  agents: { defaults: { contextPruning: { mode: "cache-ttl" } } }
+  agents: { defaults: { contextPruning: { mode: "aggressive" } } }
 }
 ```
 
-Defaults (when `mode` is `"cache-ttl"`):
-- `ttl`: `"5m"`
-- `keepLastAssistants`: `3`
-- `softTrimRatio`: `0.3`
-- `hardClearRatio`: `0.5`
-- `minPrunableToolChars`: `50000`
-- `softTrim`: `{ maxChars: 4000, headChars: 1500, tailChars: 1500 }`
-- `hardClear`: `{ enabled: true, placeholder: "[Old tool result content cleared]" }`
-
-Example (cache-ttl tuned):
+Example (adaptive tuned):
 ```json5
 {
   agents: {
     defaults: {
       contextPruning: {
-        mode: "cache-ttl",
-        ttl: "5m",
+        mode: "adaptive",
         keepLastAssistants: 3,
         softTrimRatio: 0.3,
         hardClearRatio: 0.5,
@@ -1737,12 +1742,9 @@ Z.AI models are available as `zai/<model>` (e.g. `zai/glm-4.7`) and require
   `30m`. Set `0m` to disable.
 - `model`: optional override model for heartbeat runs (`provider/model`).
 - `includeReasoning`: when `true`, heartbeats will also deliver the separate `Reasoning:` message when available (same shape as `/reasoning on`). Default: `false`.
-- `activeHours`: optional local-time window that controls when heartbeats run.
-  - `start`: start time (HH:MM, 24h). Inclusive.
-  - `end`: end time (HH:MM, 24h). Exclusive. Use `"24:00"` for end-of-day.
-  - `timezone`: `"user"` (default), `"local"`, or an IANA timezone id.
-- `target`: optional delivery channel (`last`, `whatsapp`, `telegram`, `discord`, `slack`, `signal`, `imessage`, `none`). Default: `last`.
+- `session`: optional session key to control which session the heartbeat runs in. Default: `main`.
 - `to`: optional recipient override (channel-specific id, e.g. E.164 for WhatsApp, chat id for Telegram).
+- `target`: optional delivery channel (`last`, `whatsapp`, `telegram`, `discord`, `slack`, `msteams`, `signal`, `imessage`, `none`). Default: `last`.
 - `prompt`: optional override for the heartbeat body (default: `Read HEARTBEAT.md if it exists (workspace context). Follow it strictly. Do not infer or repeat old tasks from prior chats. If nothing needs attention, reply HEARTBEAT_OK.`). Overrides are sent verbatim; include a `Read HEARTBEAT.md` line if you still want the file read.
 - `ackMaxChars`: max chars allowed after `HEARTBEAT_OK` before delivery (default: 300).
 
@@ -1773,7 +1775,6 @@ Note: `applyPatch` is only under `tools.exec`.
 - `tools.web.fetch.maxChars` (default 50000)
 - `tools.web.fetch.timeoutSeconds` (default 30)
 - `tools.web.fetch.cacheTtlMinutes` (default 15)
-- `tools.web.fetch.maxRedirects` (default 3)
 - `tools.web.fetch.userAgent` (optional override)
 - `tools.web.fetch.readability` (default true; disable to use basic HTML cleanup only)
 - `tools.web.fetch.firecrawl.enabled` (default true when an API key is set)
@@ -1840,7 +1841,7 @@ Example:
 
 `agents.defaults.subagents` configures sub-agent defaults:
 - `model`: default model for spawned sub-agents (string or `{ primary, fallbacks }`). If omitted, sub-agents inherit the caller’s model unless overridden per agent or per call.
-- `maxConcurrent`: max concurrent sub-agent runs (default 8)
+- `maxConcurrent`: max concurrent sub-agent runs (default 1)
 - `archiveAfterMinutes`: auto-archive sub-agent sessions after N minutes (default 60; set `0` to disable)
 - Per-subagent tool policy: `tools.subagents.tools.allow` / `tools.subagents.tools.deny` (deny wins)
 
@@ -1974,7 +1975,7 @@ Notes:
 
 `agents.defaults.maxConcurrent` sets the maximum number of embedded agent runs that can
 execute in parallel across sessions. Each session is still serialized (one run
-per session key at a time). Default: 4.
+per session key at a time). Default: 1.
 
 ### `agents.defaults.sandbox`
 
@@ -2452,9 +2453,6 @@ Controls session scoping, reset policy, reset triggers, and where the session st
       dm: { mode: "idle", idleMinutes: 240 },
       group: { mode: "idle", idleMinutes: 120 }
     },
-    resetByChannel: {
-      discord: { mode: "idle", idleMinutes: 10080 }
-    },
     resetTriggers: ["/new", "/reset"],
     // Default is already per-agent under ~/.clawdbot/agents/<agentId>/sessions/sessions.json
     // You can override with {agentId} templating:
@@ -2490,7 +2488,7 @@ Fields:
   - `idleMinutes`: sliding idle window in minutes. When daily + idle are both configured, whichever expires first wins.
 - `resetByType`: per-session overrides for `dm`, `group`, and `thread`.
   - If you only set legacy `session.idleMinutes` without any `reset`/`resetByType`, Clawdbot stays in idle-only mode for backward compatibility.
-- `resetByChannel`: channel-specific reset policy overrides (keyed by channel id, applies to all session types for that channel; overrides `reset`/`resetByType`).
+- `heartbeatIdleMinutes`: optional idle override for heartbeat checks (daily reset still applies when enabled).
 - `agentToAgent.maxPingPongTurns`: max reply-back turns between requester/target (0–5, default 5).
 - `sendPolicy.default`: `allow` or `deny` fallback when no rule matches.
 - `sendPolicy.rules[]`: match by `channel`, `chatType` (`direct|group|room`), or `keyPrefix` (e.g. `cron:`). First deny wins; otherwise allow.
@@ -2617,13 +2615,10 @@ Defaults:
     // noSandbox: false,
     // executablePath: "/Applications/Brave Browser.app/Contents/MacOS/Brave Browser",
     // attachOnly: false, // set true when tunneling a remote CDP to localhost
-    // snapshotDefaults: { mode: "efficient" }, // tool/CLI default snapshot preset
   }
 }
 ```
 
-Note: `browser.snapshotDefaults` only affects Clawdbot's browser tool + CLI. Direct HTTP clients must pass `mode` explicitly.
-
 ### `ui` (Appearance)
 
 Optional accent color used by the native apps for UI chrome (e.g. Talk Mode bubble tint).
@@ -2647,13 +2642,6 @@ Defaults:
 - bind: `loopback`
 - port: `18789` (single port for WS + HTTP)
 
-Bind modes:
-- `loopback`: `127.0.0.1` (local-only)
-- `lan`: `0.0.0.0` (all interfaces)
-- `tailnet`: Tailscale IPv4 address (100.64.0.0/10)
-- `auto`: prefer loopback, fall back to LAN if loopback cannot bind
-- `custom`: `gateway.customBindHost` (IPv4), fallback to LAN if unavailable
-
 ```json5
 {
   gateway: {
@@ -2684,15 +2672,14 @@ Notes:
 - `clawdbot gateway` refuses to start unless `gateway.mode` is set to `local` (or you pass the override flag).
 - `gateway.port` controls the single multiplexed port used for WebSocket + HTTP (control UI, hooks, A2UI).
 - OpenAI Chat Completions endpoint: **disabled by default**; enable with `gateway.http.endpoints.chatCompletions.enabled: true`.
-- OpenResponses endpoint: **disabled by default**; enable with `gateway.http.endpoints.responses.enabled: true`.
 - Precedence: `--port` > `CLAWDBOT_GATEWAY_PORT` > `gateway.port` > default `18789`.
-- Non-loopback binds (`lan`/`tailnet`/`custom`, or `auto` when loopback is unavailable) require auth. Use `gateway.auth.token` (or `CLAWDBOT_GATEWAY_TOKEN`).
+- Non-loopback binds (`lan`/`tailnet`/`auto`) require auth. Use `gateway.auth.token` (or `CLAWDBOT_GATEWAY_TOKEN`).
 - The onboarding wizard generates a gateway token by default (even on loopback).
 - `gateway.remote.token` is **only** for remote CLI calls; it does not enable local gateway auth. `gateway.token` is ignored.
 
 Auth and Tailscale:
 - `gateway.auth.mode` sets the handshake requirements (`token` or `password`).
-- `gateway.auth.token` stores the shared token for token auth (used by the CLI on the same machine and as the bootstrap credential for device pairing).
+- `gateway.auth.token` stores the shared token for token auth (used by the CLI on the same machine).
 - When `gateway.auth.mode` is set, only that method is accepted (plus optional Tailscale headers).
 - `gateway.auth.password` can be set here, or via `CLAWDBOT_GATEWAY_PASSWORD` (recommended).
 - `gateway.auth.allowTailscale` allows Tailscale Serve identity headers
@@ -2701,9 +2688,6 @@ Auth and Tailscale:
   `true`, Serve requests do not need a token/password; set `false` to require
   explicit credentials. Defaults to `true` when `tailscale.mode = "serve"` and
   auth mode is not `password`.
-- After pairing, the Gateway issues **device tokens** scoped to the device role + scopes.
-  These are returned in `hello-ok.auth.deviceToken`; clients should persist and reuse them
-  instead of the shared token. Rotate/revoke via `device.token.rotate`/`device.token.revoke`.
 - `gateway.tailscale.mode: "serve"` uses Tailscale Serve (tailnet only, loopback bind).
 - `gateway.tailscale.mode: "funnel"` exposes the dashboard publicly; requires auth.
 - `gateway.tailscale.resetOnExit` resets Serve/Funnel config on shutdown.
@@ -2712,7 +2696,6 @@ Remote client defaults (CLI):
 - `gateway.remote.url` sets the default Gateway WebSocket URL for CLI calls when `gateway.mode = "remote"`.
 - `gateway.remote.token` supplies the token for remote calls (leave unset for no auth).
 - `gateway.remote.password` supplies the password for remote calls (leave unset for no auth).
-- `gateway.remote.tlsFingerprint` pins the gateway TLS cert fingerprint (sha256).
 
 macOS app behavior:
 - Clawdbot.app watches `~/.clawdbot/clawdbot.json` and switches modes live when `gateway.mode` or `gateway.remote.url` changes.
@@ -2726,36 +2709,12 @@ macOS app behavior:
     remote: {
       url: "ws://gateway.tailnet:18789",
       token: "your-token",
-      password: "your-password",
-      tlsFingerprint: "sha256:ab12cd34..."
+      password: "your-password"
     }
   }
 }
 ```
 
-### `gateway.nodes` (Node command allowlist)
-
-The Gateway enforces a per-platform command allowlist for `node.invoke`. Nodes must both
-**declare** a command and have it **allowed** by the Gateway to run it.
-
-Use this section to extend or deny commands:
-
-```json5
-{
-  gateway: {
-    nodes: {
-      allowCommands: ["custom.vendor.command"], // extra commands beyond defaults
-      denyCommands: ["sms.send"]      // block a command even if declared
-    }
-  }
-}
-```
-
-Notes:
-- `allowCommands` extends the built-in per-platform defaults.
-- `denyCommands` always wins (even if the node claims the command).
-- `node.invoke` rejects commands that are not declared by the node.
-
 ### `gateway.reload` (Config hot reload)
 
 The Gateway watches `~/.clawdbot/clawdbot.json` (or `CLAWDBOT_CONFIG_PATH`) and applies changes automatically.
@@ -3003,7 +2962,7 @@ Auto-generated certs require `openssl` on PATH; if generation fails, the bridge
 
 ### `discovery.wideArea` (Wide-Area Bonjour / unicast DNS‑SD)
 
-When enabled, the Gateway writes a unicast DNS-SD zone for `_clawdbot-gw._tcp` under `~/.clawdbot/dns/` using the standard discovery domain `clawdbot.internal.`
+When enabled, the Gateway writes a unicast DNS-SD zone for `_clawdbot-bridge._tcp` under `~/.clawdbot/dns/` using the standard discovery domain `clawdbot.internal.`
 
 To make iOS/Android discover across networks (Vienna ⇄ London), pair this with:
 - a DNS server on the gateway host serving `clawdbot.internal.` (CoreDNS is recommended)
@@ -3033,9 +2992,6 @@ Template placeholders are expanded in `tools.media.*.models[].args` and `tools.m
 | `{{From}}` | Sender identifier (E.164 for WhatsApp; may differ per channel) |
 | `{{To}}` | Destination identifier |
 | `{{MessageSid}}` | Channel message id (when available) |
-| `{{MessageSidFull}}` | Provider-specific full message id when `MessageSid` is shortened |
-| `{{ReplyToId}}` | Reply-to message id (when available) |
-| `{{ReplyToIdFull}}` | Provider-specific full reply-to id when `ReplyToId` is shortened |
 | `{{SessionId}}` | Current session UUID |
 | `{{IsNewSession}}` | `"true"` when a new session was created |
 | `{{MediaUrl}}` | Inbound media pseudo-URL (if present) |

docs/gateway/heartbeat.md

@@ -127,18 +127,26 @@ Example: two agents, only the second agent runs heartbeats.
 - `every`: heartbeat interval (duration string; default unit = minutes).
 - `model`: optional model override for heartbeat runs (`provider/model`).
 - `includeReasoning`: when enabled, also deliver the separate `Reasoning:` message when available (same shape as `/reasoning on`).
+- `session`: optional session key for heartbeat runs.
+  - `main` (default): agent main session.
+  - Explicit session key (copy from `clawdbot sessions --json` or the [sessions CLI](/cli/sessions)).
+  - Session key formats: see [Sessions](/concepts/session) and [Groups](/concepts/groups).
 - `target`:
   - `last` (default): deliver to the last used external channel.
-  - explicit channel: `whatsapp` / `telegram` / `discord` / `slack` / `signal` / `imessage`.
+  - explicit channel: `whatsapp` / `telegram` / `discord` / `slack` / `msteams` / `signal` / `imessage`.
   - `none`: run the heartbeat but **do not deliver** externally.
-- `to`: optional recipient override (E.164 for WhatsApp, chat id for Telegram, etc.).
+- `to`: optional recipient override (channel-specific id, e.g. E.164 for WhatsApp or a Telegram chat id).
 - `prompt`: overrides the default prompt body (not merged).
 - `ackMaxChars`: max chars allowed after `HEARTBEAT_OK` before delivery.
 
 ## Delivery behavior
 
-- Heartbeats run in each agent’s **main session** (`agent:<id>:<mainKey>`), or `global`
-  when `session.scope = "global"`.
+- Heartbeats run in the agent’s main session by default (`agent:<id>:<mainKey>`),
+  or `global` when `session.scope = "global"`. Set `session` to override to a
+  specific channel session (Discord/WhatsApp/etc.).
+- `session` only affects the run context; delivery is controlled by `target` and `to`.
+- To deliver to a specific channel/recipient, set `target` + `to`. With
+  `target: "last"`, delivery uses the last external channel for that session.
 - If the main queue is busy, the heartbeat is skipped and retried later.
 - If `target` resolves to no external destination, the run still happens but no
   outbound message is sent.

docs/platforms/mac/release.md

@@ -30,17 +30,17 @@ Notes:
 # From repo root; set release IDs so Sparkle feed is enabled.
 # APP_BUILD must be numeric + monotonic for Sparkle compare.
 BUNDLE_ID=com.clawdbot.mac \
-APP_VERSION=2026.1.20 \
+APP_VERSION=2026.1.21 \
 APP_BUILD="$(git rev-list --count HEAD)" \
 BUILD_CONFIG=release \
 SIGN_IDENTITY="Developer ID Application: <Developer Name> (<TEAMID>)" \
 scripts/package-mac-app.sh
 
 # Zip for distribution (includes resource forks for Sparkle delta support)
-ditto -c -k --sequesterRsrc --keepParent dist/Clawdbot.app dist/Clawdbot-2026.1.20.zip
+ditto -c -k --sequesterRsrc --keepParent dist/Clawdbot.app dist/Clawdbot-2026.1.21.zip
 
 # Optional: also build a styled DMG for humans (drag to /Applications)
-scripts/create-dmg.sh dist/Clawdbot.app dist/Clawdbot-2026.1.20.dmg
+scripts/create-dmg.sh dist/Clawdbot.app dist/Clawdbot-2026.1.21.dmg
 
 # Recommended: build + notarize/staple zip + DMG
 # First, create a keychain profile once:
@@ -48,26 +48,26 @@ scripts/create-dmg.sh dist/Clawdbot.app dist/Clawdbot-2026.1.20.dmg
 #     --apple-id "<apple-id>" --team-id "<team-id>" --password "<app-specific-password>"
 NOTARIZE=1 NOTARYTOOL_PROFILE=clawdbot-notary \
 BUNDLE_ID=com.clawdbot.mac \
-APP_VERSION=2026.1.20 \
+APP_VERSION=2026.1.21 \
 APP_BUILD="$(git rev-list --count HEAD)" \
 BUILD_CONFIG=release \
 SIGN_IDENTITY="Developer ID Application: <Developer Name> (<TEAMID>)" \
 scripts/package-mac-dist.sh
 
 # Optional: ship dSYM alongside the release
-ditto -c -k --keepParent apps/macos/.build/release/Clawdbot.app.dSYM dist/Clawdbot-2026.1.20.dSYM.zip
+ditto -c -k --keepParent apps/macos/.build/release/Clawdbot.app.dSYM dist/Clawdbot-2026.1.21.dSYM.zip
 ```
 
 ## Appcast entry
 Use the release note generator so Sparkle renders formatted HTML notes:
 ```bash
-SPARKLE_PRIVATE_KEY_FILE=/path/to/ed25519-private-key scripts/make_appcast.sh dist/Clawdbot-2026.1.20.zip https://raw.githubusercontent.com/clawdbot/clawdbot/main/appcast.xml
+SPARKLE_PRIVATE_KEY_FILE=/path/to/ed25519-private-key scripts/make_appcast.sh dist/Clawdbot-2026.1.21.zip https://raw.githubusercontent.com/clawdbot/clawdbot/main/appcast.xml
 ```
 Generates HTML release notes from `CHANGELOG.md` (via [`scripts/changelog-to-html.sh`](https://github.com/clawdbot/clawdbot/blob/main/scripts/changelog-to-html.sh)) and embeds them in the appcast entry.
 Commit the updated `appcast.xml` alongside the release assets (zip + dSYM) when publishing.
 
 ## Publish & verify
-- Upload `Clawdbot-2026.1.20.zip` (and `Clawdbot-2026.1.20.dSYM.zip`) to the GitHub release for tag `v2026.1.20`.
+- Upload `Clawdbot-2026.1.21.zip` (and `Clawdbot-2026.1.21.dSYM.zip`) to the GitHub release for tag `v2026.1.21`.
 - Ensure the raw appcast URL matches the baked feed: `https://raw.githubusercontent.com/clawdbot/clawdbot/main/appcast.xml`.
 - Sanity checks:
   - `curl -I https://raw.githubusercontent.com/clawdbot/clawdbot/main/appcast.xml` returns 200.

docs/tools/exec-approvals.md

@@ -134,6 +134,10 @@ When a prompt is required, the gateway broadcasts `exec.approval.requested` to o
 The Control UI and macOS app resolve it via `exec.approval.resolve`, then the gateway forwards the
 approved request to the node host.
 
+When approvals are required, the exec tool returns immediately with an approval id. Use that id to
+correlate later system events (`Exec finished` / `Exec denied`). If no decision arrives before the
+timeout, the request is treated as an approval timeout and surfaced as a denial reason.
+
 The confirmation dialog includes:
 - command + args
 - cwd
@@ -162,11 +166,13 @@ Security notes:
 ## System events
 
 Exec lifecycle is surfaced as system messages:
-- `exec.started`
-- `exec.finished`
-- `exec.denied`
+- `Exec running` (only if the command exceeds the running notice threshold)
+- `Exec finished`
+- `Exec denied`
 
 These are posted to the agent’s session after the node reports the event.
+Gateway-host exec approvals emit the same lifecycle events when the command finishes (and optionally when running longer than the threshold).
+Approval-gated execs reuse the approval id as the `runId` in these messages for easy correlation.
 
 ## Implications
 

docs/tools/exec.md

@@ -38,6 +38,7 @@ Notes:
 ## Config
 
 - `tools.exec.notifyOnExit` (default: true): when true, backgrounded exec sessions enqueue a system event and request a heartbeat on exit.
+- `tools.exec.approvalRunningNoticeMs` (default: 10000): emit a single “running” notice when an approval-gated exec runs longer than this (0 disables).
 - `tools.exec.host` (default: `sandbox`)
 - `tools.exec.security` (default: `deny` for sandbox, `allowlist` for gateway + node when unset)
 - `tools.exec.ask` (default: `on-miss`)
@@ -92,6 +93,11 @@ Example:
 Sandboxed agents can require per-request approval before `exec` runs on the gateway or node host.
 See [Exec approvals](/tools/exec-approvals) for the policy, allowlist, and UI flow.
 
+When approvals are required, the exec tool returns immediately with
+`status: "approval-pending"` and an approval id. Once approved (or denied / timed out),
+the Gateway emits system events (`Exec finished` / `Exec denied`). If the command is still
+running after `tools.exec.approvalRunningNoticeMs`, a single `Exec running` notice is emitted.
+
 ## Allowlist + safe bins
 
 Allowlist enforcement matches **resolved binary paths only** (no basename matches). When

docs/tools/lobster.md

@@ -0,0 +1,109 @@
+---
+title: Lobster
+description: Typed workflow runtime for Clawdbot — composable pipelines with approval gates.
+---
+
+# Lobster
+
+Lobster is a workflow shell that lets Clawdbot run multi-step tool sequences as a single, deterministic operation with explicit approval checkpoints.
+
+## Why
+
+Today, complex workflows require many back-and-forth tool calls. Each call costs tokens, and the LLM has to orchestrate every step. Lobster moves that orchestration into a typed runtime:
+
+- **One call instead of many**: Clawdbot calls `lobster.run(...)` once and gets a structured result.
+- **Approvals built in**: Side effects (send email, post comment) halt the workflow until explicitly approved.
+- **Resumable**: Halted workflows return a token; approve and resume without re-running everything.
+
+## Example: Email triage
+
+Without Lobster:
+```
+User: "Check my email and draft replies"
+→ clawdbot calls gmail.list
+→ LLM summarizes
+→ User: "draft replies to #2 and #5"
+→ LLM drafts
+→ User: "send #2"
+→ clawdbot calls gmail.send
+(repeat daily, no memory of what was triaged)
+```
+
+With Lobster:
+```
+clawdbot calls: lobster.run("email.triage --limit 20")
+
+Returns:
+{
+  "status": "needs_approval",
+  "output": {
+    "summary": "5 need replies, 2 need action",
+    "drafts": [...]
+  },
+  "requiresApproval": {
+    "prompt": "Send 2 draft replies?",
+    "resumeToken": "..."
+  }
+}
+
+User approves → clawdbot calls: lobster.resume(token, approve: true)
+→ Emails sent
+```
+
+One workflow. Deterministic. Safe.
+
+## Enable
+
+Lobster is an **optional** plugin tool. Enable it in your agent config:
+
+```json
+{
+  "agents": {
+    "list": [{
+      "id": "main",
+      "tools": {
+        "allow": ["lobster"]
+      }
+    }]
+  }
+}
+```
+
+You also need the `lobster` CLI installed locally.
+
+## Actions
+
+### `run`
+
+Execute a Lobster pipeline in tool mode.
+
+```json
+{
+  "action": "run",
+  "pipeline": "gog.gmail.search --query 'newer_than:1d' | email.triage",
+  "timeoutMs": 30000
+}
+```
+
+### `resume`
+
+Continue a halted workflow after approval.
+
+```json
+{
+  "action": "resume",
+  "token": "<resumeToken>",
+  "approve": true
+}
+```
+
+## Security
+
+- **Local subprocess only** — no network calls from the plugin itself.
+- **No secrets** — Lobster doesn't manage OAuth; it calls clawd tools that do.
+- **Sandbox-aware** — disabled when `ctx.sandboxed` is true.
+- **Hardened** — `lobsterPath` must be absolute if specified; timeouts and output caps enforced.
+
+## Learn more
+
+- [Lobster repo](https://github.com/vignesh07/lobster) — runtime, commands, and workflow examples.

extensions/bluebubbles/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clawdbot/bluebubbles",
-  "version": "2026.1.21-1",
+  "version": "2026.1.21",
   "type": "module",
   "description": "Clawdbot BlueBubbles channel plugin",
   "clawdbot": {

extensions/copilot-proxy/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clawdbot/copilot-proxy",
-  "version": "2026.1.20-2",
+  "version": "2026.1.21",
   "type": "module",
   "description": "Clawdbot Copilot Proxy provider plugin",
   "clawdbot": {

extensions/diagnostics-otel/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clawdbot/diagnostics-otel",
-  "version": "2026.1.20-2",
+  "version": "2026.1.21",
   "type": "module",
   "description": "Clawdbot diagnostics OpenTelemetry exporter",
   "clawdbot": {
@@ -10,15 +10,15 @@
   },
   "dependencies": {
     "@opentelemetry/api": "^1.9.0",
-    "@opentelemetry/api-logs": "^0.210.0",
-    "@opentelemetry/exporter-logs-otlp-http": "^0.210.0",
-    "@opentelemetry/exporter-metrics-otlp-http": "^0.210.0",
-    "@opentelemetry/exporter-trace-otlp-http": "^0.210.0",
-    "@opentelemetry/resources": "^2.4.0",
-    "@opentelemetry/sdk-logs": "^0.210.0",
-    "@opentelemetry/sdk-metrics": "^2.4.0",
-    "@opentelemetry/sdk-node": "^0.210.0",
-    "@opentelemetry/sdk-trace-base": "^2.4.0",
+    "@opentelemetry/api-logs": "^0.211.0",
+    "@opentelemetry/exporter-logs-otlp-http": "^0.211.0",
+    "@opentelemetry/exporter-metrics-otlp-http": "^0.211.0",
+    "@opentelemetry/exporter-trace-otlp-http": "^0.211.0",
+    "@opentelemetry/resources": "^2.5.0",
+    "@opentelemetry/sdk-logs": "^0.211.0",
+    "@opentelemetry/sdk-metrics": "^2.5.0",
+    "@opentelemetry/sdk-node": "^0.211.0",
+    "@opentelemetry/sdk-trace-base": "^2.5.0",
     "@opentelemetry/semantic-conventions": "^1.39.0"
   }
 }

extensions/discord/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clawdbot/discord",
-  "version": "2026.1.20-2",
+  "version": "2026.1.21",
   "type": "module",
   "description": "Clawdbot Discord channel plugin",
   "clawdbot": {

extensions/google-antigravity-auth/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clawdbot/google-antigravity-auth",
-  "version": "2026.1.20-2",
+  "version": "2026.1.21",
   "type": "module",
   "description": "Clawdbot Google Antigravity OAuth provider plugin",
   "clawdbot": {

extensions/google-gemini-cli-auth/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clawdbot/google-gemini-cli-auth",
-  "version": "2026.1.20-2",
+  "version": "2026.1.21",
   "type": "module",
   "description": "Clawdbot Gemini CLI OAuth provider plugin",
   "clawdbot": {

extensions/imessage/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clawdbot/imessage",
-  "version": "2026.1.20-2",
+  "version": "2026.1.21",
   "type": "module",
   "description": "Clawdbot iMessage channel plugin",
   "clawdbot": {

extensions/lobster/README.md

@@ -0,0 +1,38 @@
+# Lobster (plugin)
+
+Adds the `lobster` agent tool as an **optional** plugin tool.
+
+## What this is
+
+- Lobster is a standalone workflow shell (typed JSON-first pipelines + approvals/resume).
+- This plugin integrates Lobster with Clawdbot *without core changes*.
+
+## Enable
+
+Because this tool can trigger side effects (via workflows), it is registered with `optional: true`.
+
+Enable it in an agent allowlist:
+
+```json
+{
+  "agents": {
+    "list": [
+      {
+        "id": "main",
+        "tools": {
+          "allow": [
+            "lobster" // plugin id (enables all tools from this plugin)
+          ]
+        }
+      }
+    ]
+  }
+}
+```
+
+## Security
+
+- Runs the `lobster` executable as a local subprocess.
+- Does not manage OAuth/tokens.
+- Uses timeouts, stdout caps, and strict JSON envelope parsing.
+- Prefer an absolute `lobsterPath` in production to avoid PATH hijack.

extensions/lobster/SKILL.md

@@ -0,0 +1,90 @@
+# Lobster
+
+Lobster executes multi-step workflows with approval checkpoints. Use it when:
+
+- User wants a repeatable automation (triage, monitor, sync)
+- Actions need human approval before executing (send, post, delete)
+- Multiple tool calls should run as one deterministic operation
+
+## When to use Lobster
+
+| User intent | Use Lobster? |
+|-------------|--------------|
+| "Triage my email" | Yes — multi-step, may send replies |
+| "Send a message" | No — single action, use message tool directly |
+| "Check my email every morning and ask before replying" | Yes — scheduled workflow with approval |
+| "What's the weather?" | No — simple query |
+| "Monitor this PR and notify me of changes" | Yes — stateful, recurring |
+
+## Basic usage
+
+### Run a pipeline
+
+```json
+{
+  "action": "run",
+  "pipeline": "gog.gmail.search --query 'newer_than:1d' --max 20 | email.triage"
+}
+```
+
+Returns structured result:
+```json
+{
+  "protocolVersion": 1,
+  "ok": true,
+  "status": "ok",
+  "output": [{ "summary": {...}, "items": [...] }],
+  "requiresApproval": null
+}
+```
+
+### Handle approval
+
+If the workflow needs approval:
+```json
+{
+  "status": "needs_approval",
+  "output": [],
+  "requiresApproval": {
+    "prompt": "Send 3 draft replies?",
+    "items": [...],
+    "resumeToken": "..."
+  }
+}
+```
+
+Present the prompt to the user. If they approve:
+```json
+{
+  "action": "resume",
+  "token": "<resumeToken>",
+  "approve": true
+}
+```
+
+## Example workflows
+
+### Email triage
+```
+gog.gmail.search --query 'newer_than:1d' --max 20 | email.triage
+```
+Fetches recent emails, classifies into buckets (needs_reply, needs_action, fyi).
+
+### Email triage with approval gate
+```
+gog.gmail.search --query 'newer_than:1d' | email.triage | approve --prompt 'Process these?'
+```
+Same as above, but halts for approval before returning.
+
+## Key behaviors
+
+- **Deterministic**: Same input → same output (no LLM variance in pipeline execution)
+- **Approval gates**: `approve` command halts execution, returns token
+- **Resumable**: Use `resume` action with token to continue
+- **Structured output**: Always returns JSON envelope with `protocolVersion`
+
+## Don't use Lobster for
+
+- Simple single-action requests (just use the tool directly)
+- Queries that need LLM interpretation mid-flow
+- One-off tasks that won't be repeated

extensions/lobster/clawdbot.plugin.json

@@ -0,0 +1,8 @@
+{
+  "id": "lobster",
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {}
+  }
+}

extensions/lobster/index.ts

@@ -0,0 +1,13 @@
+import type { ClawdbotPluginApi } from "../../src/plugins/types.js";
+
+import { createLobsterTool } from "./src/lobster-tool.js";
+
+export default function register(api: ClawdbotPluginApi) {
+  api.registerTool(
+    (ctx) => {
+      if (ctx.sandboxed) return null;
+      return createLobsterTool(api);
+    },
+    { optional: true },
+  );
+}

extensions/lobster/package.json

@@ -0,0 +1,9 @@
+{
+  "name": "@clawdbot/lobster",
+  "version": "2026.1.17-1",
+  "type": "module",
+  "description": "Lobster workflow tool plugin (typed pipelines + resumable approvals)",
+  "clawdbot": {
+    "extensions": ["./index.ts"]
+  }
+}

extensions/lobster/src/lobster-tool.test.ts

@@ -0,0 +1,197 @@
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+
+import { describe, expect, it } from "vitest";
+
+import type { ClawdbotPluginApi, ClawdbotPluginToolContext } from "../../../src/plugins/types.js";
+import { createLobsterTool } from "./lobster-tool.js";
+
+async function writeFakeLobster(params: {
+  payload?: unknown;
+  stdout?: string;
+  stderr?: string;
+  exitCode?: number;
+  delayMs?: number;
+}) {
+  const dir = await fs.mkdtemp(path.join(os.tmpdir(), "clawdbot-lobster-plugin-"));
+  const binPath = path.join(dir, "lobster");
+
+  const payload = params.stdout ?? JSON.stringify(params.payload ?? null);
+  const delay = Math.max(0, params.delayMs ?? 0);
+  const exitCode = Number.isFinite(params.exitCode) ? params.exitCode : 0;
+  const stderr = params.stderr ? String(params.stderr) : "";
+
+  const file = `#!/usr/bin/env node\n` +
+    `setTimeout(() => {\n` +
+    `  if (${JSON.stringify(stderr)}.length) process.stderr.write(${JSON.stringify(stderr)});\n` +
+    `  process.stdout.write(${JSON.stringify(payload)});\n` +
+    `  process.exit(${exitCode});\n` +
+    `}, ${delay});\n`;
+
+  await fs.writeFile(binPath, file, { encoding: "utf8", mode: 0o755 });
+  return { dir, binPath };
+}
+
+function fakeApi(): ClawdbotPluginApi {
+  return {
+    id: "lobster",
+    name: "lobster",
+    source: "test",
+    config: {} as any,
+    runtime: { version: "test" } as any,
+    logger: { info() {}, warn() {}, error() {}, debug() {} },
+    registerTool() {},
+    registerHttpHandler() {},
+    registerChannel() {},
+    registerGatewayMethod() {},
+    registerCli() {},
+    registerService() {},
+    registerProvider() {},
+    resolvePath: (p) => p,
+  };
+}
+
+function fakeCtx(overrides: Partial<ClawdbotPluginToolContext> = {}): ClawdbotPluginToolContext {
+  return {
+    config: {} as any,
+    workspaceDir: "/tmp",
+    agentDir: "/tmp",
+    agentId: "main",
+    sessionKey: "main",
+    messageChannel: undefined,
+    agentAccountId: undefined,
+    sandboxed: false,
+    ...overrides,
+  };
+}
+
+describe("lobster plugin tool", () => {
+  it("runs lobster and returns parsed envelope in details", async () => {
+    const fake = await writeFakeLobster({
+      payload: { ok: true, status: "ok", output: [{ hello: "world" }], requiresApproval: null },
+    });
+
+    const tool = createLobsterTool(fakeApi());
+    const res = await tool.execute("call1", {
+      action: "run",
+      pipeline: "noop",
+      lobsterPath: fake.binPath,
+      timeoutMs: 1000,
+    });
+
+    expect(res.details).toMatchObject({ ok: true, status: "ok" });
+  });
+
+  it("requires absolute lobsterPath when provided", async () => {
+    const tool = createLobsterTool(fakeApi());
+    await expect(
+      tool.execute("call2", {
+        action: "run",
+        pipeline: "noop",
+        lobsterPath: "./lobster",
+      }),
+    ).rejects.toThrow(/absolute path/);
+  });
+
+  it("rejects invalid JSON from lobster", async () => {
+    const dir = await fs.mkdtemp(path.join(os.tmpdir(), "clawdbot-lobster-plugin-bad-"));
+    const binPath = path.join(dir, "lobster");
+    await fs.writeFile(binPath, `#!/usr/bin/env node\nprocess.stdout.write('nope');\n`, {
+      encoding: "utf8",
+      mode: 0o755,
+    });
+
+    const tool = createLobsterTool(fakeApi());
+    await expect(
+      tool.execute("call3", {
+        action: "run",
+        pipeline: "noop",
+        lobsterPath: binPath,
+      }),
+    ).rejects.toThrow(/invalid JSON/);
+  });
+
+  it("errors on timeout", async () => {
+    const fake = await writeFakeLobster({
+      payload: { ok: true, status: "ok", output: [], requiresApproval: null },
+      delayMs: 250,
+    });
+
+    const tool = createLobsterTool(fakeApi());
+    await expect(
+      tool.execute("call4", {
+        action: "run",
+        pipeline: "noop",
+        lobsterPath: fake.binPath,
+        timeoutMs: 50,
+      }),
+    ).rejects.toThrow(/timed out/);
+  });
+
+  it("caps stdout", async () => {
+    const fake = await writeFakeLobster({
+      stdout: "x".repeat(2000),
+    });
+
+    const tool = createLobsterTool(fakeApi());
+    await expect(
+      tool.execute("call5", {
+        action: "run",
+        pipeline: "noop",
+        lobsterPath: fake.binPath,
+        maxStdoutBytes: 128,
+      }),
+    ).rejects.toThrow(/maxStdoutBytes/);
+  });
+
+  it("returns stderr in non-zero exit errors", async () => {
+    const fake = await writeFakeLobster({
+      stdout: "",
+      stderr: "boom",
+      exitCode: 2,
+    });
+
+    const tool = createLobsterTool(fakeApi());
+    await expect(
+      tool.execute("call6", {
+        action: "run",
+        pipeline: "noop",
+        lobsterPath: fake.binPath,
+      }),
+    ).rejects.toThrow(/boom/);
+  });
+
+  it("aborts via signal", async () => {
+    const fake = await writeFakeLobster({
+      payload: { ok: true, status: "ok", output: [], requiresApproval: null },
+      delayMs: 200,
+    });
+
+    const tool = createLobsterTool(fakeApi());
+    const controller = new AbortController();
+    const promise = tool.execute(
+      "call7",
+      {
+        action: "run",
+        pipeline: "noop",
+        lobsterPath: fake.binPath,
+      },
+      controller.signal,
+    );
+
+    controller.abort();
+    await expect(promise).rejects.toThrow(/aborted/);
+  });
+
+  it("can be gated off in sandboxed contexts", async () => {
+    const api = fakeApi();
+    const factoryTool = (ctx: ClawdbotPluginToolContext) => {
+      if (ctx.sandboxed) return null;
+      return createLobsterTool(api);
+    };
+
+    expect(factoryTool(fakeCtx({ sandboxed: true }))).toBeNull();
+    expect(factoryTool(fakeCtx({ sandboxed: false }))?.name).toBe("lobster");
+  });
+});

extensions/lobster/src/lobster-tool.ts

@@ -0,0 +1,211 @@
+import { Type } from "@sinclair/typebox";
+import { spawn } from "node:child_process";
+import path from "node:path";
+
+import type { ClawdbotPluginApi } from "../../../src/plugins/types.js";
+
+type LobsterEnvelope =
+  | {
+      ok: true;
+      status: "ok" | "needs_approval" | "cancelled";
+      output: unknown[];
+      requiresApproval: null | {
+        type: "approval_request";
+        prompt: string;
+        items: unknown[];
+        resumeToken?: string;
+      };
+    }
+  | {
+      ok: false;
+      error: { type?: string; message: string };
+    };
+
+function resolveExecutablePath(lobsterPathRaw: string | undefined) {
+  const lobsterPath = lobsterPathRaw?.trim() || "lobster";
+  if (lobsterPath !== "lobster" && !path.isAbsolute(lobsterPath)) {
+    throw new Error("lobsterPath must be an absolute path (or omit to use PATH)");
+  }
+  return lobsterPath;
+}
+
+async function runLobsterSubprocess(params: {
+  execPath: string;
+  argv: string[];
+  cwd: string;
+  timeoutMs: number;
+  maxStdoutBytes: number;
+  signal?: AbortSignal;
+}) {
+  const { execPath, argv, cwd } = params;
+  const timeoutMs = Math.max(200, params.timeoutMs);
+  const maxStdoutBytes = Math.max(1024, params.maxStdoutBytes);
+
+  return await new Promise<{ stdout: string }>((resolve, reject) => {
+    if (params.signal?.aborted) {
+      reject(new Error("lobster subprocess aborted"));
+      return;
+    }
+
+    const child = spawn(execPath, argv, {
+      cwd,
+      stdio: ["ignore", "pipe", "pipe"],
+      env: {
+        ...process.env,
+        LOBSTER_MODE: "tool",
+      },
+    });
+
+    let stdout = "";
+    let stdoutBytes = 0;
+    let stderr = "";
+    let settled = false;
+
+    const finish = (fn: () => void) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      if (params.signal) params.signal.removeEventListener("abort", onAbort);
+      fn();
+    };
+
+    const onAbort = () => {
+      try {
+        child.kill("SIGKILL");
+      } finally {
+        finish(() => reject(new Error("lobster subprocess aborted")));
+      }
+    };
+
+    params.signal?.addEventListener("abort", onAbort);
+
+    child.stdout?.setEncoding("utf8");
+    child.stderr?.setEncoding("utf8");
+
+    child.stdout?.on("data", (chunk) => {
+      const str = String(chunk);
+      stdoutBytes += Buffer.byteLength(str, "utf8");
+      if (stdoutBytes > maxStdoutBytes) {
+        try {
+          child.kill("SIGKILL");
+        } finally {
+          finish(() => reject(new Error("lobster output exceeded maxStdoutBytes")));
+        }
+        return;
+      }
+      stdout += str;
+    });
+
+    child.stderr?.on("data", (chunk) => {
+      stderr += String(chunk);
+    });
+
+    const timer = setTimeout(() => {
+      try {
+        child.kill("SIGKILL");
+      } finally {
+        finish(() => reject(new Error("lobster subprocess timed out")));
+      }
+    }, timeoutMs);
+
+    child.once("error", (err) => {
+      finish(() => reject(err));
+    });
+
+    child.once("exit", (code) => {
+      if (code !== 0) {
+        finish(() =>
+          reject(new Error(`lobster failed (${code ?? "?"}): ${stderr.trim() || stdout.trim()}`)),
+        );
+        return;
+      }
+      finish(() => resolve({ stdout }));
+    });
+  });
+}
+
+function parseEnvelope(stdout: string): LobsterEnvelope {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(stdout);
+  } catch {
+    throw new Error("lobster returned invalid JSON");
+  }
+
+  if (!parsed || typeof parsed !== "object") {
+    throw new Error("lobster returned invalid JSON envelope");
+  }
+
+  const ok = (parsed as { ok?: unknown }).ok;
+  if (ok === true || ok === false) {
+    return parsed as LobsterEnvelope;
+  }
+
+  throw new Error("lobster returned invalid JSON envelope");
+}
+
+export function createLobsterTool(api: ClawdbotPluginApi) {
+  return {
+    name: "lobster",
+    description:
+      "Run Lobster pipelines as a local-first workflow runtime (typed JSON envelope + resumable approvals).",
+    parameters: Type.Object({
+      // NOTE: Prefer string enums in tool schemas; some providers reject unions/anyOf.
+      action: Type.Unsafe<"run" | "resume">({ type: "string", enum: ["run", "resume"] }),
+      pipeline: Type.Optional(Type.String()),
+      token: Type.Optional(Type.String()),
+      approve: Type.Optional(Type.Boolean()),
+      lobsterPath: Type.Optional(Type.String()),
+      cwd: Type.Optional(Type.String()),
+      timeoutMs: Type.Optional(Type.Number()),
+      maxStdoutBytes: Type.Optional(Type.Number()),
+    }),
+    async execute(_id: string, params: Record<string, unknown>, signal?: AbortSignal) {
+      const action = String(params.action || "").trim();
+      if (!action) throw new Error("action required");
+
+      const execPath = resolveExecutablePath(
+        typeof params.lobsterPath === "string" ? params.lobsterPath : undefined,
+      );
+      const cwd = typeof params.cwd === "string" && params.cwd.trim() ? params.cwd.trim() : process.cwd();
+      const timeoutMs = typeof params.timeoutMs === "number" ? params.timeoutMs : 20_000;
+      const maxStdoutBytes = typeof params.maxStdoutBytes === "number" ? params.maxStdoutBytes : 512_000;
+
+      const argv = (() => {
+        if (action === "run") {
+          const pipeline = typeof params.pipeline === "string" ? params.pipeline : "";
+          if (!pipeline.trim()) throw new Error("pipeline required");
+          return ["run", "--mode", "tool", pipeline];
+        }
+        if (action === "resume") {
+          const token = typeof params.token === "string" ? params.token : "";
+          if (!token.trim()) throw new Error("token required");
+          const approve = params.approve;
+          if (typeof approve !== "boolean") throw new Error("approve required");
+          return ["resume", "--token", token, "--approve", approve ? "yes" : "no"];
+        }
+        throw new Error(`Unknown action: ${action}`);
+      })();
+
+      if (api.runtime?.version && api.logger?.debug) {
+        api.logger.debug(`lobster plugin runtime=${api.runtime.version}`);
+      }
+
+      const { stdout } = await runLobsterSubprocess({
+        execPath,
+        argv,
+        cwd,
+        timeoutMs,
+        maxStdoutBytes,
+        signal,
+      });
+
+      const envelope = parseEnvelope(stdout);
+
+      return {
+        content: [{ type: "text", text: JSON.stringify(envelope, null, 2) }],
+        details: envelope,
+      };
+    },
+  };
+}

extensions/matrix/CHANGELOG.md

@@ -1,6 +1,6 @@
 # Changelog
 
-## 2026.1.20-2
+## 2026.1.21
 
 ### Changes
 - Version alignment with core Clawdbot release numbers.

extensions/matrix/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clawdbot/matrix",
-  "version": "2026.1.20-2",
+  "version": "2026.1.21",
   "type": "module",
   "description": "Clawdbot Matrix channel plugin",
   "clawdbot": {

extensions/memory-core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clawdbot/memory-core",
-  "version": "2026.1.20-2",
+  "version": "2026.1.21",
   "type": "module",
   "description": "Clawdbot core memory search plugin",
   "clawdbot": {

extensions/memory-lancedb/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clawdbot/memory-lancedb",
-  "version": "2026.1.20-2",
+  "version": "2026.1.21",
   "type": "module",
   "description": "Clawdbot LanceDB-backed long-term memory plugin with auto-recall/capture",
   "dependencies": {

extensions/msteams/CHANGELOG.md

@@ -1,6 +1,6 @@
 # Changelog
 
-## 2026.1.20-2
+## 2026.1.21
 
 ### Changes
 - Version alignment with core Clawdbot release numbers.

extensions/msteams/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clawdbot/msteams",
-  "version": "2026.1.20-2",
+  "version": "2026.1.21",
   "type": "module",
   "description": "Clawdbot Microsoft Teams channel plugin",
   "clawdbot": {

extensions/nextcloud-talk/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clawdbot/nextcloud-talk",
-  "version": "2026.1.20-2",
+  "version": "2026.1.21",
   "type": "module",
   "description": "Clawdbot Nextcloud Talk channel plugin",
   "clawdbot": {

extensions/nostr/CHANGELOG.md

@@ -1,6 +1,6 @@
 # Changelog
 
-## 2026.1.20-2
+## 2026.1.21
 
 ### Changes
 - Version alignment with core Clawdbot release numbers.

extensions/nostr/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clawdbot/nostr",
-  "version": "2026.1.20-2",
+  "version": "2026.1.21",
   "type": "module",
   "description": "Clawdbot Nostr channel plugin for NIP-04 encrypted DMs",
   "clawdbot": {
@@ -25,7 +25,7 @@
   },
   "dependencies": {
     "clawdbot": "workspace:*",
-    "nostr-tools": "^2.10.4",
+    "nostr-tools": "^2.19.4",
     "zod": "^4.3.5"
   }
 }

extensions/signal/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clawdbot/signal",
-  "version": "2026.1.20-2",
+  "version": "2026.1.21",
   "type": "module",
   "description": "Clawdbot Signal channel plugin",
   "clawdbot": {

extensions/slack/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clawdbot/slack",
-  "version": "2026.1.20-2",
+  "version": "2026.1.21",
   "type": "module",
   "description": "Clawdbot Slack channel plugin",
   "clawdbot": {

extensions/telegram/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clawdbot/telegram",
-  "version": "2026.1.20-2",
+  "version": "2026.1.21",
   "type": "module",
   "description": "Clawdbot Telegram channel plugin",
   "clawdbot": {

extensions/voice-call/CHANGELOG.md

@@ -1,6 +1,6 @@
 # Changelog
 
-## 2026.1.20-2
+## 2026.1.21
 
 ### Changes
 - Version alignment with core Clawdbot release numbers.

extensions/voice-call/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clawdbot/voice-call",
-  "version": "2026.1.20-2",
+  "version": "2026.1.21",
   "type": "module",
   "description": "Clawdbot voice-call plugin",
   "dependencies": {

extensions/whatsapp/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clawdbot/whatsapp",
-  "version": "2026.1.20-2",
+  "version": "2026.1.21",
   "type": "module",
   "description": "Clawdbot WhatsApp channel plugin",
   "clawdbot": {

extensions/zalo/CHANGELOG.md

@@ -1,6 +1,6 @@
 # Changelog
 
-## 2026.1.20-2
+## 2026.1.21
 
 ### Changes
 - Version alignment with core Clawdbot release numbers.

extensions/zalo/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clawdbot/zalo",
-  "version": "2026.1.20-2",
+  "version": "2026.1.21",
   "type": "module",
   "description": "Clawdbot Zalo channel plugin",
   "clawdbot": {
@@ -28,6 +28,6 @@
   },
   "dependencies": {
     "clawdbot": "workspace:*",
-    "undici": "7.18.2"
+    "undici": "7.19.0"
   }
 }

extensions/zalouser/CHANGELOG.md

@@ -1,6 +1,6 @@
 # Changelog
 
-## 2026.1.20-2
+## 2026.1.21
 
 ### Changes
 - Version alignment with core Clawdbot release numbers.

extensions/zalouser/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clawdbot/zalouser",
-  "version": "2026.1.20-2",
+  "version": "2026.1.21",
   "type": "module",
   "description": "Clawdbot Zalo Personal Account plugin via zca-cli",
   "dependencies": {

package.json

@@ -1,6 +1,6 @@
 {
   "name": "clawdbot",
-  "version": "2026.1.20-2",
+  "version": "2026.1.21",
   "description": "WhatsApp gateway CLI (Baileys web) with Pi RPC agent",
   "type": "module",
   "main": "dist/index.js",
@@ -153,10 +153,10 @@
     "@grammyjs/transformer-throttler": "^1.2.1",
     "@homebridge/ciao": "^1.3.4",
     "@lydell/node-pty": "1.2.0-beta.3",
-    "@mariozechner/pi-agent-core": "0.49.2",
-    "@mariozechner/pi-ai": "0.49.2",
-    "@mariozechner/pi-coding-agent": "0.49.2",
-    "@mariozechner/pi-tui": "0.49.2",
+    "@mariozechner/pi-agent-core": "0.49.3",
+    "@mariozechner/pi-ai": "0.49.3",
+    "@mariozechner/pi-coding-agent": "0.49.3",
+    "@mariozechner/pi-tui": "0.49.3",
     "@mozilla/readability": "^0.6.0",
     "@sinclair/typebox": "0.34.47",
     "@slack/bolt": "^4.6.0",
@@ -166,7 +166,7 @@
     "body-parser": "^2.2.2",
     "chalk": "^5.6.2",
     "chokidar": "^5.0.0",
-    "chromium-bidi": "13.0.0",
+    "chromium-bidi": "13.0.1",
     "cli-highlight": "^2.1.11",
     "commander": "^14.0.2",
     "croner": "^9.1.0",
@@ -192,7 +192,7 @@
     "sqlite-vec": "0.1.7-alpha.2",
     "tar": "7.5.4",
     "tslog": "^4.10.2",
-    "undici": "^7.18.2",
+    "undici": "^7.19.0",
     "ws": "^8.19.0",
     "yaml": "^2.8.2",
     "zod": "^4.3.5"
@@ -209,7 +209,7 @@
     "@types/body-parser": "^1.19.6",
     "@types/express": "^5.0.6",
     "@types/markdown-it": "^14.1.2",
-    "@types/node": "^25.0.9",
+    "@types/node": "^25.0.10",
     "@types/proper-lockfile": "^4.1.4",
     "@types/qrcode-terminal": "^0.12.2",
     "@types/ws": "^8.18.1",

src/agents/bash-tools.exec.approval-id.test.ts

@@ -0,0 +1,71 @@
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+vi.mock("./tools/gateway.js", () => ({
+  callGatewayTool: vi.fn(),
+}));
+
+vi.mock("./tools/nodes-utils.js", () => ({
+  listNodes: vi.fn(async () => [
+    { nodeId: "node-1", commands: ["system.run"], platform: "darwin" },
+  ]),
+  resolveNodeIdFromList: vi.fn((nodes: Array<{ nodeId: string }>) => nodes[0]?.nodeId),
+}));
+
+describe("exec approvals", () => {
+  let previousHome: string | undefined;
+
+  beforeEach(async () => {
+    previousHome = process.env.HOME;
+    const tempDir = await fs.mkdtemp(path.join(os.tmpdir(), "clawdbot-test-"));
+    process.env.HOME = tempDir;
+  });
+
+  afterEach(() => {
+    vi.resetAllMocks();
+    if (previousHome === undefined) {
+      delete process.env.HOME;
+    } else {
+      process.env.HOME = previousHome;
+    }
+  });
+
+  it("reuses approval id as the node runId", async () => {
+    const { callGatewayTool } = await import("./tools/gateway.js");
+    let invokeParams: unknown;
+    let resolveInvoke: (() => void) | undefined;
+    const invokeSeen = new Promise<void>((resolve) => {
+      resolveInvoke = resolve;
+    });
+
+    vi.mocked(callGatewayTool).mockImplementation(async (method, _opts, params) => {
+      if (method === "exec.approval.request") {
+        return { decision: "allow-once" };
+      }
+      if (method === "node.invoke") {
+        invokeParams = params;
+        resolveInvoke?.();
+        return { ok: true };
+      }
+      return { ok: true };
+    });
+
+    const { createExecTool } = await import("./bash-tools.exec.js");
+    const tool = createExecTool({
+      host: "node",
+      ask: "always",
+      approvalRunningNoticeMs: 0,
+    });
+
+    const result = await tool.execute("call1", { command: "ls -la" });
+    expect(result.details.status).toBe("approval-pending");
+    const approvalId = (result.details as { approvalId: string }).approvalId;
+
+    await invokeSeen;
+
+    const runId = (invokeParams as { params?: { runId?: string } } | undefined)?.params?.runId;
+    expect(runId).toBe(approvalId);
+  });
+});

src/agents/pi-embedded-helpers.sanitize-session-messages-images.keeps-tool-call-tool-result-ids-unchanged.test.ts

@@ -1,15 +1,7 @@
 import type { AgentMessage } from "@mariozechner/pi-agent-core";
 import { describe, expect, it } from "vitest";
 import { sanitizeSessionMessagesImages } from "./pi-embedded-helpers.js";
-import { DEFAULT_AGENTS_FILENAME } from "./workspace.js";
 
-const _makeFile = (overrides: Partial<WorkspaceBootstrapFile>): WorkspaceBootstrapFile => ({
-  name: DEFAULT_AGENTS_FILENAME,
-  path: "/tmp/AGENTS.md",
-  content: "",
-  missing: false,
-  ...overrides,
-});
 describe("sanitizeSessionMessagesImages", () => {
   it("keeps tool call + tool result IDs unchanged by default", async () => {
     const input = [
@@ -50,7 +42,8 @@ describe("sanitizeSessionMessagesImages", () => {
     expect(toolResult.role).toBe("toolResult");
     expect(toolResult.toolCallId).toBe("call_123|fc_456");
   });
-  it("sanitizes tool call + tool result IDs when enabled", async () => {
+
+  it("sanitizes tool call + tool result IDs in standard mode (preserves underscores)", async () => {
     const input = [
       {
         role: "assistant",
@@ -82,6 +75,7 @@ describe("sanitizeSessionMessagesImages", () => {
     const toolCall = (assistant.content as Array<{ type?: string; id?: string }>).find(
       (b) => b.type === "toolCall",
     );
+    // Standard mode preserves underscores for readability, replaces invalid chars
     expect(toolCall?.id).toBe("call_123_fc_456");
 
     const toolResult = out[1] as unknown as {
@@ -91,6 +85,50 @@ describe("sanitizeSessionMessagesImages", () => {
     expect(toolResult.role).toBe("toolResult");
     expect(toolResult.toolCallId).toBe("call_123_fc_456");
   });
+
+  it("sanitizes tool call + tool result IDs in strict mode (alphanumeric only)", async () => {
+    const input = [
+      {
+        role: "assistant",
+        content: [
+          {
+            type: "toolCall",
+            id: "call_123|fc_456",
+            name: "read",
+            arguments: { path: "package.json" },
+          },
+        ],
+      },
+      {
+        role: "toolResult",
+        toolCallId: "call_123|fc_456",
+        toolName: "read",
+        content: [{ type: "text", text: "ok" }],
+        isError: false,
+      },
+    ] satisfies AgentMessage[];
+
+    const out = await sanitizeSessionMessagesImages(input, "test", {
+      sanitizeToolCallIds: true,
+      toolCallIdMode: "strict",
+    });
+
+    const assistant = out[0] as unknown as { role?: string; content?: unknown };
+    expect(assistant.role).toBe("assistant");
+    expect(Array.isArray(assistant.content)).toBe(true);
+    const toolCall = (assistant.content as Array<{ type?: string; id?: string }>).find(
+      (b) => b.type === "toolCall",
+    );
+    // Strict mode strips all non-alphanumeric characters
+    expect(toolCall?.id).toBe("call123fc456");
+
+    const toolResult = out[1] as unknown as {
+      role?: string;
+      toolCallId?: string;
+    };
+    expect(toolResult.role).toBe("toolResult");
+    expect(toolResult.toolCallId).toBe("call123fc456");
+  });
   it("drops assistant blocks after a tool call when enforceToolCallLast is enabled", async () => {
     const input = [
       {

src/agents/pi-embedded-helpers.sanitize-session-messages-images.removes-empty-assistant-text-blocks-but-preserves.test.ts

@@ -1,15 +1,7 @@
 import type { AgentMessage } from "@mariozechner/pi-agent-core";
 import { describe, expect, it } from "vitest";
 import { sanitizeSessionMessagesImages } from "./pi-embedded-helpers.js";
-import { DEFAULT_AGENTS_FILENAME } from "./workspace.js";
 
-const _makeFile = (overrides: Partial<WorkspaceBootstrapFile>): WorkspaceBootstrapFile => ({
-  name: DEFAULT_AGENTS_FILENAME,
-  path: "/tmp/AGENTS.md",
-  content: "",
-  missing: false,
-  ...overrides,
-});
 describe("sanitizeSessionMessagesImages", () => {
   it("removes empty assistant text blocks but preserves tool calls", async () => {
     const input = [
@@ -30,7 +22,8 @@ describe("sanitizeSessionMessagesImages", () => {
     expect(content).toHaveLength(1);
     expect((content as Array<{ type?: string }>)[0]?.type).toBe("toolCall");
   });
-  it("sanitizes tool ids for assistant blocks and tool results when enabled", async () => {
+
+  it("sanitizes tool ids in standard mode (preserves underscores)", async () => {
     const input = [
       {
         role: "assistant",
@@ -55,6 +48,7 @@ describe("sanitizeSessionMessagesImages", () => {
       sanitizeToolCallIds: true,
     });
 
+    // Standard mode preserves underscores for readability
     const assistant = out[0] as { content?: Array<{ id?: string }> };
     expect(assistant.content?.[0]?.id).toBe("call_abc_item_123");
     expect(assistant.content?.[1]?.id).toBe("call_abc_item_456");
@@ -62,6 +56,41 @@ describe("sanitizeSessionMessagesImages", () => {
     const toolResult = out[1] as { toolUseId?: string };
     expect(toolResult.toolUseId).toBe("call_abc_item_123");
   });
+
+  it("sanitizes tool ids in strict mode (alphanumeric only)", async () => {
+    const input = [
+      {
+        role: "assistant",
+        content: [
+          { type: "toolUse", id: "call_abc|item:123", name: "test", input: {} },
+          {
+            type: "toolCall",
+            id: "call_abc|item:456",
+            name: "exec",
+            arguments: {},
+          },
+        ],
+      },
+      {
+        role: "toolResult",
+        toolUseId: "call_abc|item:123",
+        content: [{ type: "text", text: "ok" }],
+      },
+    ] satisfies AgentMessage[];
+
+    const out = await sanitizeSessionMessagesImages(input, "test", {
+      sanitizeToolCallIds: true,
+      toolCallIdMode: "strict",
+    });
+
+    // Strict mode strips all non-alphanumeric characters
+    const assistant = out[0] as { content?: Array<{ id?: string }> };
+    expect(assistant.content?.[0]?.id).toBe("callabcitem123");
+    expect(assistant.content?.[1]?.id).toBe("callabcitem456");
+
+    const toolResult = out[1] as { toolUseId?: string };
+    expect(toolResult.toolUseId).toBe("callabcitem123");
+  });
   it("filters whitespace-only assistant text blocks", async () => {
     const input = [
       {

src/agents/pi-embedded-helpers.sanitizetoolcallid.test.ts

@@ -1,22 +1,43 @@
 import { describe, expect, it } from "vitest";
 import { sanitizeToolCallId } from "./pi-embedded-helpers.js";
-import { DEFAULT_AGENTS_FILENAME } from "./workspace.js";
 
-const _makeFile = (overrides: Partial<WorkspaceBootstrapFile>): WorkspaceBootstrapFile => ({
-  name: DEFAULT_AGENTS_FILENAME,
-  path: "/tmp/AGENTS.md",
-  content: "",
-  missing: false,
-  ...overrides,
-});
 describe("sanitizeToolCallId", () => {
-  it("keeps valid tool call IDs", () => {
-    expect(sanitizeToolCallId("call_abc-123")).toBe("call_abc-123");
+  describe("standard mode (default)", () => {
+    it("keeps valid alphanumeric tool call IDs", () => {
+      expect(sanitizeToolCallId("callabc123")).toBe("callabc123");
+    });
+    it("keeps underscores and hyphens for readability", () => {
+      expect(sanitizeToolCallId("call_abc-123")).toBe("call_abc-123");
+      expect(sanitizeToolCallId("call_abc_def")).toBe("call_abc_def");
+    });
+    it("replaces invalid characters with underscores", () => {
+      expect(sanitizeToolCallId("call_abc|item:456")).toBe("call_abc_item_456");
+    });
+    it("returns default for empty IDs", () => {
+      expect(sanitizeToolCallId("")).toBe("default_tool_id");
+    });
   });
-  it("replaces invalid characters with underscores", () => {
-    expect(sanitizeToolCallId("call_abc|item:456")).toBe("call_abc_item_456");
+
+  describe("strict mode (alphanumeric only)", () => {
+    it("strips all non-alphanumeric characters", () => {
+      expect(sanitizeToolCallId("call_abc-123", "strict")).toBe("callabc123");
+      expect(sanitizeToolCallId("call_abc|item:456", "strict")).toBe("callabcitem456");
+      expect(sanitizeToolCallId("whatsapp_login_1768799841527_1", "strict")).toBe(
+        "whatsapplogin17687998415271",
+      );
+    });
+    it("returns default for empty IDs", () => {
+      expect(sanitizeToolCallId("", "strict")).toBe("defaulttoolid");
+    });
   });
-  it("returns default for empty IDs", () => {
-    expect(sanitizeToolCallId("")).toBe("default_tool_id");
+
+  describe("strict9 mode (Mistral tool call IDs)", () => {
+    it("returns alphanumeric IDs with length 9", () => {
+      const out = sanitizeToolCallId("call_abc|item:456", "strict9");
+      expect(out).toMatch(/^[a-zA-Z0-9]{9}$/);
+    });
+    it("returns default for empty IDs", () => {
+      expect(sanitizeToolCallId("", "strict9")).toMatch(/^[a-zA-Z0-9]{9}$/);
+    });
   });
 });

src/agents/pi-embedded-helpers.ts

@@ -50,4 +50,5 @@ export {
 } from "./pi-embedded-helpers/turns.js";
 export type { EmbeddedContextFile, FailoverReason } from "./pi-embedded-helpers/types.js";
 
+export type { ToolCallIdMode } from "./tool-call-id.js";
 export { isValidCloudCodeAssistToolId, sanitizeToolCallId } from "./tool-call-id.js";

src/agents/pi-embedded-helpers/images.ts

@@ -1,5 +1,6 @@
 import type { AgentMessage, AgentToolResult } from "@mariozechner/pi-agent-core";
 
+import type { ToolCallIdMode } from "../tool-call-id.js";
 import { sanitizeToolCallIdsForCloudCodeAssist } from "../tool-call-id.js";
 import { sanitizeContentBlocksImages } from "../tool-images.js";
 import { stripThoughtSignatures } from "./bootstrap.js";
@@ -32,6 +33,13 @@ export async function sanitizeSessionMessagesImages(
   label: string,
   options?: {
     sanitizeToolCallIds?: boolean;
+    /**
+     * Mode for tool call ID sanitization:
+     * - "standard" (default, preserves _-)
+     * - "strict" (alphanumeric only)
+     * - "strict9" (alphanumeric only, length 9)
+     */
+    toolCallIdMode?: ToolCallIdMode;
     enforceToolCallLast?: boolean;
     preserveSignatures?: boolean;
     sanitizeThoughtSignatures?: {
@@ -43,7 +51,7 @@ export async function sanitizeSessionMessagesImages(
   // We sanitize historical session messages because Anthropic can reject a request
   // if the transcript contains oversized base64 images (see MAX_IMAGE_DIMENSION_PX).
   const sanitizedIds = options?.sanitizeToolCallIds
-    ? sanitizeToolCallIdsForCloudCodeAssist(messages)
+    ? sanitizeToolCallIdsForCloudCodeAssist(messages, options.toolCallIdMode)
     : messages;
   const out: AgentMessage[] = [];
   for (const msg of sanitizedIds) {

src/agents/pi-embedded-runner.sanitize-session-history.test.ts

@@ -54,6 +54,25 @@ describe("sanitizeSessionHistory", () => {
     );
   });
 
+  it("sanitizes tool call ids with strict9 for Mistral models", async () => {
+    vi.mocked(helpers.isGoogleModelApi).mockReturnValue(false);
+
+    await sanitizeSessionHistory({
+      messages: mockMessages,
+      modelApi: "openai-responses",
+      provider: "openrouter",
+      modelId: "mistralai/devstral-2512:free",
+      sessionManager: mockSessionManager,
+      sessionId: "test-session",
+    });
+
+    expect(helpers.sanitizeSessionMessagesImages).toHaveBeenCalledWith(
+      mockMessages,
+      "session:history",
+      expect.objectContaining({ sanitizeToolCallIds: true, toolCallIdMode: "strict9" }),
+    );
+  });
+
   it("does not sanitize tool call ids for non-Google, non-OpenAI APIs", async () => {
     vi.mocked(helpers.isGoogleModelApi).mockReturnValue(false);
 

src/agents/pi-embedded-runner/google.ts

@@ -14,6 +14,8 @@ import { log } from "./logger.js";
 import { describeUnknownError } from "./utils.js";
 import { isAntigravityClaude } from "../pi-embedded-helpers/google.js";
 import { cleanToolSchemaForGemini } from "../pi-tools.schema.js";
+import { normalizeProviderId } from "../model-selection.js";
+import type { ToolCallIdMode } from "../tool-call-id.js";
 
 const GOOGLE_TURN_ORDERING_CUSTOM_TYPE = "google-turn-ordering-bootstrap";
 const GOOGLE_SCHEMA_UNSUPPORTED_KEYWORDS = new Set([
@@ -44,12 +46,29 @@ const OPENAI_TOOL_CALL_ID_APIS = new Set([
   "openai-responses",
   "openai-codex-responses",
 ]);
+const MISTRAL_MODEL_HINTS = [
+  "mistral",
+  "mixtral",
+  "codestral",
+  "pixtral",
+  "devstral",
+  "ministral",
+  "mistralai",
+];
 
 function shouldSanitizeToolCallIds(modelApi?: string | null): boolean {
   if (!modelApi) return false;
   return isGoogleModelApi(modelApi) || OPENAI_TOOL_CALL_ID_APIS.has(modelApi);
 }
 
+function isMistralModel(params: { provider?: string | null; modelId?: string | null }): boolean {
+  const provider = normalizeProviderId(params.provider ?? "");
+  if (provider === "mistral") return true;
+  const modelId = (params.modelId ?? "").toLowerCase();
+  if (!modelId) return false;
+  return MISTRAL_MODEL_HINTS.some((hint) => modelId.includes(hint));
+}
+
 function findUnsupportedSchemaKeywords(schema: unknown, path: string): string[] {
   if (!schema || typeof schema !== "object") return [];
   if (Array.isArray(schema)) {
@@ -191,12 +210,16 @@ export async function sanitizeSessionHistory(params: {
   sessionId: string;
 }): Promise<AgentMessage[]> {
   const isAntigravityClaudeModel = isAntigravityClaude(params.modelApi, params.modelId);
-  const provider = (params.provider ?? "").toLowerCase();
+  const provider = normalizeProviderId(params.provider ?? "");
   const modelId = (params.modelId ?? "").toLowerCase();
   const isOpenRouterGemini =
     (provider === "openrouter" || provider === "opencode") && modelId.includes("gemini");
+  const isMistral = isMistralModel({ provider, modelId });
+  const toolCallIdMode: ToolCallIdMode | undefined = isMistral ? "strict9" : undefined;
+  const sanitizeToolCallIds = shouldSanitizeToolCallIds(params.modelApi) || isMistral;
   const sanitizedImages = await sanitizeSessionMessagesImages(params.messages, "session:history", {
-    sanitizeToolCallIds: shouldSanitizeToolCallIds(params.modelApi),
+    sanitizeToolCallIds,
+    toolCallIdMode,
     enforceToolCallLast: params.modelApi === "anthropic-messages",
     preserveSignatures: params.modelApi === "google-antigravity" && isAntigravityClaudeModel,
     sanitizeThoughtSignatures: isOpenRouterGemini

src/agents/pi-tools.ts

@@ -84,6 +84,7 @@ function resolveExecConfig(cfg: ClawdbotConfig | undefined) {
     pathPrepend: globalExec?.pathPrepend,
     backgroundMs: globalExec?.backgroundMs,
     timeoutSec: globalExec?.timeoutSec,
+    approvalRunningNoticeMs: globalExec?.approvalRunningNoticeMs,
     cleanupMs: globalExec?.cleanupMs,
     notifyOnExit: globalExec?.notifyOnExit,
     applyPatch: globalExec?.applyPatch,
@@ -219,6 +220,8 @@ export function createClawdbotCodingTools(options?: {
     messageProvider: options?.messageProvider,
     backgroundMs: options?.exec?.backgroundMs ?? execConfig.backgroundMs,
     timeoutSec: options?.exec?.timeoutSec ?? execConfig.timeoutSec,
+    approvalRunningNoticeMs:
+      options?.exec?.approvalRunningNoticeMs ?? execConfig.approvalRunningNoticeMs,
     notifyOnExit: options?.exec?.notifyOnExit ?? execConfig.notifyOnExit,
     sandbox: sandbox
       ? {

src/agents/tool-call-id.test.ts

@@ -7,106 +7,262 @@ import {
 } from "./tool-call-id.js";
 
 describe("sanitizeToolCallIdsForCloudCodeAssist", () => {
-  it("is a no-op for already-valid non-colliding IDs", () => {
-    const input = [
-      {
-        role: "assistant",
-        content: [{ type: "toolCall", id: "call_1", name: "read", arguments: {} }],
-      },
-      {
-        role: "toolResult",
-        toolCallId: "call_1",
-        toolName: "read",
-        content: [{ type: "text", text: "ok" }],
-      },
-    ] satisfies AgentMessage[];
+  describe("standard mode (default)", () => {
+    it("is a no-op for already-valid non-colliding IDs", () => {
+      const input = [
+        {
+          role: "assistant",
+          content: [{ type: "toolCall", id: "call_1", name: "read", arguments: {} }],
+        },
+        {
+          role: "toolResult",
+          toolCallId: "call_1",
+          toolName: "read",
+          content: [{ type: "text", text: "ok" }],
+        },
+      ] satisfies AgentMessage[];
 
-    const out = sanitizeToolCallIdsForCloudCodeAssist(input);
-    expect(out).toBe(input);
+      const out = sanitizeToolCallIdsForCloudCodeAssist(input);
+      expect(out).toBe(input);
+    });
+
+    it("replaces invalid characters with underscores (preserves readability)", () => {
+      const input = [
+        {
+          role: "assistant",
+          content: [{ type: "toolCall", id: "call|item:123", name: "read", arguments: {} }],
+        },
+        {
+          role: "toolResult",
+          toolCallId: "call|item:123",
+          toolName: "read",
+          content: [{ type: "text", text: "ok" }],
+        },
+      ] satisfies AgentMessage[];
+
+      const out = sanitizeToolCallIdsForCloudCodeAssist(input);
+      expect(out).not.toBe(input);
+
+      const assistant = out[0] as Extract<AgentMessage, { role: "assistant" }>;
+      const toolCall = assistant.content?.[0] as { id?: string };
+      // Standard mode preserves underscores for readability
+      expect(toolCall.id).toBe("call_item_123");
+      expect(isValidCloudCodeAssistToolId(toolCall.id as string)).toBe(true);
+
+      const result = out[1] as Extract<AgentMessage, { role: "toolResult" }>;
+      expect(result.toolCallId).toBe(toolCall.id);
+    });
+
+    it("avoids collisions when sanitization would produce duplicate IDs", () => {
+      const input = [
+        {
+          role: "assistant",
+          content: [
+            { type: "toolCall", id: "call_a|b", name: "read", arguments: {} },
+            { type: "toolCall", id: "call_a:b", name: "read", arguments: {} },
+          ],
+        },
+        {
+          role: "toolResult",
+          toolCallId: "call_a|b",
+          toolName: "read",
+          content: [{ type: "text", text: "one" }],
+        },
+        {
+          role: "toolResult",
+          toolCallId: "call_a:b",
+          toolName: "read",
+          content: [{ type: "text", text: "two" }],
+        },
+      ] satisfies AgentMessage[];
+
+      const out = sanitizeToolCallIdsForCloudCodeAssist(input);
+      expect(out).not.toBe(input);
+
+      const assistant = out[0] as Extract<AgentMessage, { role: "assistant" }>;
+      const a = assistant.content?.[0] as { id?: string };
+      const b = assistant.content?.[1] as { id?: string };
+      expect(typeof a.id).toBe("string");
+      expect(typeof b.id).toBe("string");
+      expect(a.id).not.toBe(b.id);
+      expect(isValidCloudCodeAssistToolId(a.id as string)).toBe(true);
+      expect(isValidCloudCodeAssistToolId(b.id as string)).toBe(true);
+
+      const r1 = out[1] as Extract<AgentMessage, { role: "toolResult" }>;
+      const r2 = out[2] as Extract<AgentMessage, { role: "toolResult" }>;
+      expect(r1.toolCallId).toBe(a.id);
+      expect(r2.toolCallId).toBe(b.id);
+    });
+
+    it("caps tool call IDs at 40 chars while preserving uniqueness", () => {
+      const longA = `call_${"a".repeat(60)}`;
+      const longB = `call_${"a".repeat(59)}b`;
+      const input = [
+        {
+          role: "assistant",
+          content: [
+            { type: "toolCall", id: longA, name: "read", arguments: {} },
+            { type: "toolCall", id: longB, name: "read", arguments: {} },
+          ],
+        },
+        {
+          role: "toolResult",
+          toolCallId: longA,
+          toolName: "read",
+          content: [{ type: "text", text: "one" }],
+        },
+        {
+          role: "toolResult",
+          toolCallId: longB,
+          toolName: "read",
+          content: [{ type: "text", text: "two" }],
+        },
+      ] satisfies AgentMessage[];
+
+      const out = sanitizeToolCallIdsForCloudCodeAssist(input);
+      const assistant = out[0] as Extract<AgentMessage, { role: "assistant" }>;
+      const a = assistant.content?.[0] as { id?: string };
+      const b = assistant.content?.[1] as { id?: string };
+
+      expect(typeof a.id).toBe("string");
+      expect(typeof b.id).toBe("string");
+      expect(a.id).not.toBe(b.id);
+      expect(a.id?.length).toBeLessThanOrEqual(40);
+      expect(b.id?.length).toBeLessThanOrEqual(40);
+      expect(isValidCloudCodeAssistToolId(a.id as string)).toBe(true);
+      expect(isValidCloudCodeAssistToolId(b.id as string)).toBe(true);
+
+      const r1 = out[1] as Extract<AgentMessage, { role: "toolResult" }>;
+      const r2 = out[2] as Extract<AgentMessage, { role: "toolResult" }>;
+      expect(r1.toolCallId).toBe(a.id);
+      expect(r2.toolCallId).toBe(b.id);
+    });
   });
 
-  it("avoids collisions when sanitization would produce duplicate IDs", () => {
-    const input = [
-      {
-        role: "assistant",
-        content: [
-          { type: "toolCall", id: "call_a|b", name: "read", arguments: {} },
-          { type: "toolCall", id: "call_a:b", name: "read", arguments: {} },
-        ],
-      },
-      {
-        role: "toolResult",
-        toolCallId: "call_a|b",
-        toolName: "read",
-        content: [{ type: "text", text: "one" }],
-      },
-      {
-        role: "toolResult",
-        toolCallId: "call_a:b",
-        toolName: "read",
-        content: [{ type: "text", text: "two" }],
-      },
-    ] satisfies AgentMessage[];
+  describe("strict mode (alphanumeric only)", () => {
+    it("strips underscores and hyphens from tool call IDs", () => {
+      const input = [
+        {
+          role: "assistant",
+          content: [
+            {
+              type: "toolCall",
+              id: "whatsapp_login_1768799841527_1",
+              name: "login",
+              arguments: {},
+            },
+          ],
+        },
+        {
+          role: "toolResult",
+          toolCallId: "whatsapp_login_1768799841527_1",
+          toolName: "login",
+          content: [{ type: "text", text: "ok" }],
+        },
+      ] satisfies AgentMessage[];
 
-    const out = sanitizeToolCallIdsForCloudCodeAssist(input);
-    expect(out).not.toBe(input);
+      const out = sanitizeToolCallIdsForCloudCodeAssist(input, "strict");
+      expect(out).not.toBe(input);
 
-    const assistant = out[0] as Extract<AgentMessage, { role: "assistant" }>;
-    const a = assistant.content?.[0] as { id?: string };
-    const b = assistant.content?.[1] as { id?: string };
-    expect(typeof a.id).toBe("string");
-    expect(typeof b.id).toBe("string");
-    expect(a.id).not.toBe(b.id);
-    expect(isValidCloudCodeAssistToolId(a.id as string)).toBe(true);
-    expect(isValidCloudCodeAssistToolId(b.id as string)).toBe(true);
+      const assistant = out[0] as Extract<AgentMessage, { role: "assistant" }>;
+      const toolCall = assistant.content?.[0] as { id?: string };
+      // Strict mode strips all non-alphanumeric characters
+      expect(toolCall.id).toBe("whatsapplogin17687998415271");
+      expect(isValidCloudCodeAssistToolId(toolCall.id as string, "strict")).toBe(true);
 
-    const r1 = out[1] as Extract<AgentMessage, { role: "toolResult" }>;
-    const r2 = out[2] as Extract<AgentMessage, { role: "toolResult" }>;
-    expect(r1.toolCallId).toBe(a.id);
-    expect(r2.toolCallId).toBe(b.id);
+      const result = out[1] as Extract<AgentMessage, { role: "toolResult" }>;
+      expect(result.toolCallId).toBe(toolCall.id);
+    });
+
+    it("avoids collisions with alphanumeric-only suffixes", () => {
+      const input = [
+        {
+          role: "assistant",
+          content: [
+            { type: "toolCall", id: "call_a|b", name: "read", arguments: {} },
+            { type: "toolCall", id: "call_a:b", name: "read", arguments: {} },
+          ],
+        },
+        {
+          role: "toolResult",
+          toolCallId: "call_a|b",
+          toolName: "read",
+          content: [{ type: "text", text: "one" }],
+        },
+        {
+          role: "toolResult",
+          toolCallId: "call_a:b",
+          toolName: "read",
+          content: [{ type: "text", text: "two" }],
+        },
+      ] satisfies AgentMessage[];
+
+      const out = sanitizeToolCallIdsForCloudCodeAssist(input, "strict");
+      expect(out).not.toBe(input);
+
+      const assistant = out[0] as Extract<AgentMessage, { role: "assistant" }>;
+      const a = assistant.content?.[0] as { id?: string };
+      const b = assistant.content?.[1] as { id?: string };
+      expect(typeof a.id).toBe("string");
+      expect(typeof b.id).toBe("string");
+      expect(a.id).not.toBe(b.id);
+      // Both should be strictly alphanumeric
+      expect(isValidCloudCodeAssistToolId(a.id as string, "strict")).toBe(true);
+      expect(isValidCloudCodeAssistToolId(b.id as string, "strict")).toBe(true);
+      // Should not contain underscores or hyphens
+      expect(a.id).not.toMatch(/[_-]/);
+      expect(b.id).not.toMatch(/[_-]/);
+
+      const r1 = out[1] as Extract<AgentMessage, { role: "toolResult" }>;
+      const r2 = out[2] as Extract<AgentMessage, { role: "toolResult" }>;
+      expect(r1.toolCallId).toBe(a.id);
+      expect(r2.toolCallId).toBe(b.id);
+    });
   });
 
-  it("caps tool call IDs at 40 chars while preserving uniqueness", () => {
-    const longA = `call_${"a".repeat(60)}`;
-    const longB = `call_${"a".repeat(59)}b`;
-    const input = [
-      {
-        role: "assistant",
-        content: [
-          { type: "toolCall", id: longA, name: "read", arguments: {} },
-          { type: "toolCall", id: longB, name: "read", arguments: {} },
-        ],
-      },
-      {
-        role: "toolResult",
-        toolCallId: longA,
-        toolName: "read",
-        content: [{ type: "text", text: "one" }],
-      },
-      {
-        role: "toolResult",
-        toolCallId: longB,
-        toolName: "read",
-        content: [{ type: "text", text: "two" }],
-      },
-    ] satisfies AgentMessage[];
+  describe("strict9 mode (Mistral tool call IDs)", () => {
+    it("enforces alphanumeric IDs with length 9", () => {
+      const input = [
+        {
+          role: "assistant",
+          content: [
+            { type: "toolCall", id: "call_abc|item:123", name: "read", arguments: {} },
+            { type: "toolCall", id: "call_abc|item:456", name: "read", arguments: {} },
+          ],
+        },
+        {
+          role: "toolResult",
+          toolCallId: "call_abc|item:123",
+          toolName: "read",
+          content: [{ type: "text", text: "one" }],
+        },
+        {
+          role: "toolResult",
+          toolCallId: "call_abc|item:456",
+          toolName: "read",
+          content: [{ type: "text", text: "two" }],
+        },
+      ] satisfies AgentMessage[];
 
-    const out = sanitizeToolCallIdsForCloudCodeAssist(input);
-    const assistant = out[0] as Extract<AgentMessage, { role: "assistant" }>;
-    const a = assistant.content?.[0] as { id?: string };
-    const b = assistant.content?.[1] as { id?: string };
+      const out = sanitizeToolCallIdsForCloudCodeAssist(input, "strict9");
+      expect(out).not.toBe(input);
 
-    expect(typeof a.id).toBe("string");
-    expect(typeof b.id).toBe("string");
-    expect(a.id).not.toBe(b.id);
-    expect(a.id?.length).toBeLessThanOrEqual(40);
-    expect(b.id?.length).toBeLessThanOrEqual(40);
-    expect(isValidCloudCodeAssistToolId(a.id as string)).toBe(true);
-    expect(isValidCloudCodeAssistToolId(b.id as string)).toBe(true);
+      const assistant = out[0] as Extract<AgentMessage, { role: "assistant" }>;
+      const a = assistant.content?.[0] as { id?: string };
+      const b = assistant.content?.[1] as { id?: string };
 
-    const r1 = out[1] as Extract<AgentMessage, { role: "toolResult" }>;
-    const r2 = out[2] as Extract<AgentMessage, { role: "toolResult" }>;
-    expect(r1.toolCallId).toBe(a.id);
-    expect(r2.toolCallId).toBe(b.id);
+      expect(typeof a.id).toBe("string");
+      expect(typeof b.id).toBe("string");
+      expect(a.id).not.toBe(b.id);
+      expect(a.id?.length).toBe(9);
+      expect(b.id?.length).toBe(9);
+      expect(isValidCloudCodeAssistToolId(a.id as string, "strict9")).toBe(true);
+      expect(isValidCloudCodeAssistToolId(b.id as string, "strict9")).toBe(true);
+
+      const r1 = out[1] as Extract<AgentMessage, { role: "toolResult" }>;
+      const r2 = out[2] as Extract<AgentMessage, { role: "toolResult" }>;
+      expect(r1.toolCallId).toBe(a.id);
+      expect(r2.toolCallId).toBe(b.id);
+    });
   });
 });

src/agents/tool-call-id.ts

@@ -2,46 +2,96 @@ import { createHash } from "node:crypto";
 
 import type { AgentMessage } from "@mariozechner/pi-agent-core";
 
-export function sanitizeToolCallId(id: string): string {
-  if (!id || typeof id !== "string") return "default_tool_id";
+export type ToolCallIdMode = "standard" | "strict" | "strict9";
 
-  const cloudCodeAssistPatternReplacement = id.replace(/[^a-zA-Z0-9_-]/g, "_");
-  const trimmedInvalidStartChars = cloudCodeAssistPatternReplacement.replace(
-    /^[^a-zA-Z0-9_-]+/,
-    "",
-  );
+const STRICT9_LEN = 9;
 
-  return trimmedInvalidStartChars.length > 0 ? trimmedInvalidStartChars : "sanitized_tool_id";
+/**
+ * Sanitize a tool call ID to be compatible with various providers.
+ *
+ * - "standard" mode: allows [a-zA-Z0-9_-], better readability (default)
+ * - "strict" mode: only [a-zA-Z0-9]
+ * - "strict9" mode: only [a-zA-Z0-9], length 9 (Mistral tool call requirement)
+ */
+export function sanitizeToolCallId(id: string, mode: ToolCallIdMode = "standard"): string {
+  if (!id || typeof id !== "string") {
+    if (mode === "strict9") return "defaultid";
+    return mode === "strict" ? "defaulttoolid" : "default_tool_id";
+  }
+
+  if (mode === "strict") {
+    // Some providers require strictly alphanumeric tool call IDs.
+    const alphanumericOnly = id.replace(/[^a-zA-Z0-9]/g, "");
+    return alphanumericOnly.length > 0 ? alphanumericOnly : "sanitizedtoolid";
+  }
+
+  if (mode === "strict9") {
+    const alphanumericOnly = id.replace(/[^a-zA-Z0-9]/g, "");
+    if (alphanumericOnly.length >= STRICT9_LEN) return alphanumericOnly.slice(0, STRICT9_LEN);
+    if (alphanumericOnly.length > 0) return shortHash(alphanumericOnly, STRICT9_LEN);
+    return shortHash("sanitized", STRICT9_LEN);
+  }
+
+  // Standard mode: allow underscores and hyphens for better readability in logs
+  const sanitized = id.replace(/[^a-zA-Z0-9_-]/g, "_");
+  const trimmed = sanitized.replace(/^[^a-zA-Z0-9_-]+/, "");
+  return trimmed.length > 0 ? trimmed : "sanitized_tool_id";
 }
 
-export function isValidCloudCodeAssistToolId(id: string): boolean {
+export function isValidCloudCodeAssistToolId(
+  id: string,
+  mode: ToolCallIdMode = "standard",
+): boolean {
   if (!id || typeof id !== "string") return false;
+  if (mode === "strict") {
+    // Strictly alphanumeric for providers with tighter tool ID constraints
+    return /^[a-zA-Z0-9]+$/.test(id);
+  }
+  if (mode === "strict9") {
+    return /^[a-zA-Z0-9]{9}$/.test(id);
+  }
+  // Standard mode allows underscores and hyphens
   return /^[a-zA-Z0-9_-]+$/.test(id);
 }
 
-function shortHash(text: string): string {
-  return createHash("sha1").update(text).digest("hex").slice(0, 8);
+function shortHash(text: string, length = 8): string {
+  return createHash("sha1").update(text).digest("hex").slice(0, length);
 }
 
-function makeUniqueToolId(params: { id: string; used: Set<string> }): string {
+function makeUniqueToolId(params: { id: string; used: Set<string>; mode: ToolCallIdMode }): string {
+  if (params.mode === "strict9") {
+    const base = sanitizeToolCallId(params.id, params.mode);
+    const candidate = base.length >= STRICT9_LEN ? base.slice(0, STRICT9_LEN) : "";
+    if (candidate && !params.used.has(candidate)) return candidate;
+
+    for (let i = 0; i < 1000; i += 1) {
+      const hashed = shortHash(`${params.id}:${i}`, STRICT9_LEN);
+      if (!params.used.has(hashed)) return hashed;
+    }
+
+    return shortHash(`${params.id}:${Date.now()}`, STRICT9_LEN);
+  }
+
   const MAX_LEN = 40;
 
-  const base = sanitizeToolCallId(params.id).slice(0, MAX_LEN);
+  const base = sanitizeToolCallId(params.id, params.mode).slice(0, MAX_LEN);
   if (!params.used.has(base)) return base;
 
   const hash = shortHash(params.id);
-  const maxBaseLen = MAX_LEN - 1 - hash.length;
+  // Use separator based on mode: underscore for standard (readable), none for strict
+  const separator = params.mode === "strict" ? "" : "_";
+  const maxBaseLen = MAX_LEN - separator.length - hash.length;
   const clippedBase = base.length > maxBaseLen ? base.slice(0, maxBaseLen) : base;
-  const candidate = `${clippedBase}_${hash}`;
+  const candidate = `${clippedBase}${separator}${hash}`;
   if (!params.used.has(candidate)) return candidate;
 
   for (let i = 2; i < 1000; i += 1) {
-    const suffix = `_${i}`;
+    const suffix = params.mode === "strict" ? `x${i}` : `_${i}`;
     const next = `${candidate.slice(0, MAX_LEN - suffix.length)}${suffix}`;
     if (!params.used.has(next)) return next;
   }
 
-  const ts = `_${Date.now()}`;
+  const ts = params.mode === "strict" ? `t${Date.now()}` : `_${Date.now()}`;
   return `${candidate.slice(0, MAX_LEN - ts.length)}${ts}`;
 }
 
@@ -100,9 +150,20 @@ function rewriteToolResultIds(params: {
   } as Extract<AgentMessage, { role: "toolResult" }>;
 }
 
-export function sanitizeToolCallIdsForCloudCodeAssist(messages: AgentMessage[]): AgentMessage[] {
-  // Cloud Code Assist requires tool IDs matching ^[a-zA-Z0-9_-]+$.
-  // Sanitization can introduce collisions (e.g. `a|b` and `a:b` -> `a_b`).
+/**
+ * Sanitize tool call IDs for provider compatibility.
+ *
+ * @param messages - The messages to sanitize
+ * @param mode - "standard" (default, allows _-), "strict" (alphanumeric only), or "strict9" (alphanumeric length 9)
+ */
+export function sanitizeToolCallIdsForCloudCodeAssist(
+  messages: AgentMessage[],
+  mode: ToolCallIdMode = "standard",
+): AgentMessage[] {
+  // Standard mode: allows [a-zA-Z0-9_-] for better readability in session logs
+  // Strict mode: only [a-zA-Z0-9]
+  // Strict9 mode: only [a-zA-Z0-9], length 9 (Mistral tool call requirement)
+  // Sanitization can introduce collisions (e.g. `a|b` and `a:b` -> `a_b` or `ab`).
   // Fix by applying a stable, transcript-wide mapping and de-duping via suffix.
   const map = new Map<string, string>();
   const used = new Set<string>();
@@ -110,7 +171,7 @@ export function sanitizeToolCallIdsForCloudCodeAssist(messages: AgentMessage[]):
   const resolve = (id: string) => {
     const existing = map.get(id);
     if (existing) return existing;
-    const next = makeUniqueToolId({ id, used });
+    const next = makeUniqueToolId({ id, used, mode });
     map.set(id, next);
     used.add(next);
     return next;

src/auto-reply/reply.directive.directive-behavior.lists-allowlisted-models-model-list.test.ts

@@ -60,7 +60,7 @@ describe("directive behavior", () => {
     vi.restoreAllMocks();
   });
 
-  it("lists allowlisted models on /model list", async () => {
+  it("aliases /model list to /models", async () => {
     await withTempHome(async (home) => {
       vi.mocked(runEmbeddedPiAgent).mockReset();
       const storePath = path.join(home, "sessions.json");
@@ -84,13 +84,15 @@ describe("directive behavior", () => {
       );
 
       const text = Array.isArray(res) ? res[0]?.text : res?.text;
-      expect(text).toContain("Model listing moved.");
-      expect(text).toContain("Use: /models (providers) or /models <provider> (models)");
+      expect(text).toContain("Providers:");
+      expect(text).toContain("- anthropic");
+      expect(text).toContain("- openai");
+      expect(text).toContain("Use: /models <provider>");
       expect(text).toContain("Switch: /model <provider/model>");
       expect(runEmbeddedPiAgent).not.toHaveBeenCalled();
     });
   });
-  it("falls back to configured models when catalog is unavailable", async () => {
+  it("shows current model when catalog is unavailable", async () => {
     await withTempHome(async (home) => {
       vi.mocked(runEmbeddedPiAgent).mockReset();
       vi.mocked(loadModelCatalog).mockResolvedValueOnce([]);
@@ -116,15 +118,16 @@ describe("directive behavior", () => {
 
       const text = Array.isArray(res) ? res[0]?.text : res?.text;
       expect(text).toContain("Current: anthropic/claude-opus-4-5");
+      expect(text).toContain("Switch: /model <provider/model>");
       expect(text).toContain("Browse: /models (providers) or /models <provider> (models)");
       expect(text).toContain("More: /model status");
       expect(runEmbeddedPiAgent).not.toHaveBeenCalled();
     });
   });
-  it("includes catalog models when no allowlist is set", async () => {
+  it("includes catalog providers when no allowlist is set", async () => {
     await withTempHome(async (home) => {
       vi.mocked(runEmbeddedPiAgent).mockReset();
-      vi.mocked(loadModelCatalog).mockResolvedValueOnce([
+      vi.mocked(loadModelCatalog).mockResolvedValue([
         { id: "claude-opus-4-5", name: "Opus 4.5", provider: "anthropic" },
         { id: "gpt-4.1-mini", name: "GPT-4.1 Mini", provider: "openai" },
         { id: "grok-4", name: "Grok 4", provider: "xai" },
@@ -150,13 +153,15 @@ describe("directive behavior", () => {
       );
 
       const text = Array.isArray(res) ? res[0]?.text : res?.text;
-      expect(text).toContain("Model listing moved.");
-      expect(text).toContain("Use: /models (providers) or /models <provider> (models)");
-      expect(text).toContain("Switch: /model <provider/model>");
+      expect(text).toContain("Providers:");
+      expect(text).toContain("- anthropic");
+      expect(text).toContain("- openai");
+      expect(text).toContain("- xai");
+      expect(text).toContain("Use: /models <provider>");
       expect(runEmbeddedPiAgent).not.toHaveBeenCalled();
     });
   });
-  it("merges config allowlist models even when catalog is present", async () => {
+  it("lists config-only providers when catalog is present", async () => {
     await withTempHome(async (home) => {
       vi.mocked(runEmbeddedPiAgent).mockReset();
       // Catalog present but missing custom providers: /model should still include
@@ -172,7 +177,7 @@ describe("directive behavior", () => {
       const storePath = path.join(home, "sessions.json");
 
       const res = await getReplyFromConfig(
-        { Body: "/model list", From: "+1222", To: "+1222", CommandAuthorized: true },
+        { Body: "/models minimax", From: "+1222", To: "+1222", CommandAuthorized: true },
         {},
         {
           agents: {
@@ -201,9 +206,8 @@ describe("directive behavior", () => {
       );
 
       const text = Array.isArray(res) ? res[0]?.text : res?.text;
-      expect(text).toContain("Model listing moved.");
-      expect(text).toContain("Use: /models (providers) or /models <provider> (models)");
-      expect(text).toContain("Switch: /model <provider/model>");
+      expect(text).toContain("Model set to minimax");
+      expect(text).toContain("minimax/MiniMax-M2.1");
       expect(runEmbeddedPiAgent).not.toHaveBeenCalled();
     });
   });
@@ -230,7 +234,7 @@ describe("directive behavior", () => {
       );
 
       const text = Array.isArray(res) ? res[0]?.text : res?.text;
-      expect(text).toContain("Model listing moved.");
+      expect(text).toContain("Providers:");
       expect(text).not.toContain("missing (missing)");
       expect(runEmbeddedPiAgent).not.toHaveBeenCalled();
     });

src/auto-reply/reply.directive.directive-behavior.prefers-alias-matches-fuzzy-selection-is-ambiguous.test.ts

@@ -67,7 +67,7 @@ describe("directive behavior", () => {
       vi.mocked(runEmbeddedPiAgent).mockReset();
       const storePath = path.join(home, "sessions.json");
 
-      await getReplyFromConfig(
+      const res = await getReplyFromConfig(
         { Body: "/model ki", From: "+1222", To: "+1222", CommandAuthorized: true },
         {},
         {
@@ -103,9 +103,11 @@ describe("directive behavior", () => {
         },
       );
 
+      const text = Array.isArray(res) ? res[0]?.text : res?.text;
+      expect(text).toContain("Model set to Kimi (moonshot/kimi-k2-0905-preview).");
       assertModelSelection(storePath, {
-        model: "kimi-k2-0905-preview",
         provider: "moonshot",
+        model: "kimi-k2-0905-preview",
       });
       expect(runEmbeddedPiAgent).not.toHaveBeenCalled();
     });

src/auto-reply/reply.directive.directive-behavior.supports-fuzzy-model-matches-model-directive.test.ts

@@ -65,7 +65,7 @@ describe("directive behavior", () => {
       vi.mocked(runEmbeddedPiAgent).mockReset();
       const storePath = path.join(home, "sessions.json");
 
-      await getReplyFromConfig(
+      const res = await getReplyFromConfig(
         { Body: "/model kimi", From: "+1222", To: "+1222", CommandAuthorized: true },
         {},
         {
@@ -94,9 +94,11 @@ describe("directive behavior", () => {
         },
       );
 
+      const text = Array.isArray(res) ? res[0]?.text : res?.text;
+      expect(text).toContain("Model set to moonshot/kimi-k2-0905-preview.");
       assertModelSelection(storePath, {
-        model: "kimi-k2-0905-preview",
         provider: "moonshot",
+        model: "kimi-k2-0905-preview",
       });
       expect(runEmbeddedPiAgent).not.toHaveBeenCalled();
     });
@@ -106,7 +108,7 @@ describe("directive behavior", () => {
       vi.mocked(runEmbeddedPiAgent).mockReset();
       const storePath = path.join(home, "sessions.json");
 
-      await getReplyFromConfig(
+      const res = await getReplyFromConfig(
         {
           Body: "/model kimi-k2-0905-preview",
           From: "+1222",
@@ -140,9 +142,11 @@ describe("directive behavior", () => {
         },
       );
 
+      const text = Array.isArray(res) ? res[0]?.text : res?.text;
+      expect(text).toContain("Model set to moonshot/kimi-k2-0905-preview.");
       assertModelSelection(storePath, {
-        model: "kimi-k2-0905-preview",
         provider: "moonshot",
+        model: "kimi-k2-0905-preview",
       });
       expect(runEmbeddedPiAgent).not.toHaveBeenCalled();
     });
@@ -152,7 +156,7 @@ describe("directive behavior", () => {
       vi.mocked(runEmbeddedPiAgent).mockReset();
       const storePath = path.join(home, "sessions.json");
 
-      await getReplyFromConfig(
+      const res = await getReplyFromConfig(
         { Body: "/model moonshot/kimi", From: "+1222", To: "+1222", CommandAuthorized: true },
         {},
         {
@@ -181,9 +185,11 @@ describe("directive behavior", () => {
         },
       );
 
+      const text = Array.isArray(res) ? res[0]?.text : res?.text;
+      expect(text).toContain("Model set to moonshot/kimi-k2-0905-preview.");
       assertModelSelection(storePath, {
-        model: "kimi-k2-0905-preview",
         provider: "moonshot",
+        model: "kimi-k2-0905-preview",
       });
       expect(runEmbeddedPiAgent).not.toHaveBeenCalled();
     });

src/auto-reply/reply.directive.directive-behavior.updates-tool-verbose-during-flight-run-toggle.test.ts

@@ -187,7 +187,7 @@ describe("directive behavior", () => {
       expect(runEmbeddedPiAgent).toHaveBeenCalledOnce();
     });
   });
-  it("lists allowlisted models on /model", async () => {
+  it("shows summary on /model", async () => {
     await withTempHome(async (home) => {
       vi.mocked(runEmbeddedPiAgent).mockReset();
       const storePath = path.join(home, "sessions.json");
@@ -212,8 +212,10 @@ describe("directive behavior", () => {
 
       const text = Array.isArray(res) ? res[0]?.text : res?.text;
       expect(text).toContain("Current: anthropic/claude-opus-4-5");
+      expect(text).toContain("Switch: /model <provider/model>");
       expect(text).toContain("Browse: /models (providers) or /models <provider> (models)");
       expect(text).toContain("More: /model status");
+      expect(text).not.toContain("openai/gpt-4.1-mini");
       expect(runEmbeddedPiAgent).not.toHaveBeenCalled();
     });
   });

src/auto-reply/reply.triggers.trigger-handling.shows-quick-model-picker-grouped-by-model.test.ts

@@ -123,7 +123,7 @@ describe("trigger handling", () => {
       expect(normalized).not.toContain("image");
     });
   });
-  it("moves /model list to /models", async () => {
+  it("aliases /model list to /models", async () => {
     await withTempHome(async (home) => {
       const cfg = makeCfg(home);
       const res = await getReplyFromConfig(
@@ -143,8 +143,8 @@ describe("trigger handling", () => {
 
       const text = Array.isArray(res) ? res[0]?.text : res?.text;
       const normalized = normalizeTestText(text ?? "");
-      expect(normalized).toContain("Model listing moved.");
-      expect(normalized).toContain("Use: /models (providers) or /models <provider> (models)");
+      expect(normalized).toContain("Providers:");
+      expect(normalized).toContain("Use: /models <provider>");
       expect(normalized).toContain("Switch: /model <provider/model>");
     });
   });

src/auto-reply/reply/commands-models.ts

@@ -7,6 +7,7 @@ import {
   resolveModelRefFromString,
 } from "../../agents/model-selection.js";
 import { DEFAULT_MODEL, DEFAULT_PROVIDER } from "../../agents/defaults.js";
+import type { ClawdbotConfig } from "../../config/config.js";
 import type { ReplyPayload } from "../types.js";
 import type { CommandHandler } from "./commands-types.js";
 
@@ -68,10 +69,11 @@ function parseModelsArgs(raw: string): {
   };
 }
 
-export const handleModelsCommand: CommandHandler = async (params, allowTextCommands) => {
-  if (!allowTextCommands) return null;
-
-  const body = params.command.commandBodyNormalized.trim();
+export async function resolveModelsCommandReply(params: {
+  cfg: ClawdbotConfig;
+  commandBodyNormalized: string;
+}): Promise<ReplyPayload | null> {
+  const body = params.commandBodyNormalized.trim();
   if (!body.startsWith("/models")) return null;
 
   const argText = body.replace(/^\/models\b/i, "").trim();
@@ -164,7 +166,7 @@ export const handleModelsCommand: CommandHandler = async (params, allowTextComma
       "Use: /models <provider>",
       "Switch: /model <provider/model>",
     ];
-    return { reply: { text: lines.join("\n") }, shouldContinue: false };
+    return { text: lines.join("\n") };
   }
 
   if (!byProvider.has(provider)) {
@@ -176,7 +178,7 @@ export const handleModelsCommand: CommandHandler = async (params, allowTextComma
       "",
       "Use: /models <provider>",
     ];
-    return { reply: { text: lines.join("\n") }, shouldContinue: false };
+    return { text: lines.join("\n") };
   }
 
   const models = [...(byProvider.get(provider) ?? new Set<string>())].sort();
@@ -189,7 +191,7 @@ export const handleModelsCommand: CommandHandler = async (params, allowTextComma
       "Browse: /models",
       "Switch: /model <provider/model>",
     ];
-    return { reply: { text: lines.join("\n") }, shouldContinue: false };
+    return { text: lines.join("\n") };
   }
 
   const effectivePageSize = all ? total : pageSize;
@@ -203,7 +205,7 @@ export const handleModelsCommand: CommandHandler = async (params, allowTextComma
       `Try: /models ${provider} ${safePage}`,
       `All: /models ${provider} all`,
     ];
-    return { reply: { text: lines.join("\n") }, shouldContinue: false };
+    return { text: lines.join("\n") };
   }
 
   const startIndex = (safePage - 1) * effectivePageSize;
@@ -226,5 +228,16 @@ export const handleModelsCommand: CommandHandler = async (params, allowTextComma
   }
 
   const payload: ReplyPayload = { text: lines.join("\n") };
-  return { reply: payload, shouldContinue: false };
+  return payload;
+}
+
+export const handleModelsCommand: CommandHandler = async (params, allowTextCommands) => {
+  if (!allowTextCommands) return null;
+
+  const reply = await resolveModelsCommandReply({
+    cfg: params.cfg,
+    commandBodyNormalized: params.command.commandBodyNormalized,
+  });
+  if (!reply) return null;
+  return { reply, shouldContinue: false };
 };

src/auto-reply/reply/directive-handling.model.chat-ux.test.ts

@@ -36,7 +36,7 @@ describe("/model chat UX", () => {
     expect(reply?.text).toContain("Switch: /model <provider/model>");
   });
 
-  it("suggests closest match for typos without switching", () => {
+  it("auto-applies closest match for typos", () => {
     const directives = parseInlineDirectives("/model anthropic/claud-opus-4-5");
     const cfg = { commands: { text: true } } as unknown as ClawdbotConfig;
 
@@ -52,9 +52,11 @@ describe("/model chat UX", () => {
       provider: "anthropic",
     });
 
-    expect(resolved.modelSelection).toBeUndefined();
-    expect(resolved.errorText).toContain("Did you mean:");
-    expect(resolved.errorText).toContain("anthropic/claude-opus-4-5");
-    expect(resolved.errorText).toContain("Try: /model anthropic/claude-opus-4-5");
+    expect(resolved.modelSelection).toEqual({
+      provider: "anthropic",
+      model: "claude-opus-4-5",
+      isDefault: true,
+    });
+    expect(resolved.errorText).toBeUndefined();
   });
 });

src/auto-reply/reply/directive-handling.model.ts

@@ -20,6 +20,7 @@ import {
   resolveProviderEndpointLabel,
 } from "./directive-handling.model-picker.js";
 import type { InlineDirectives } from "./directive-handling.parse.js";
+import { resolveModelsCommandReply } from "./commands-models.js";
 import { type ModelDirectiveSelection, resolveModelDirectiveSelection } from "./model-selection.js";
 
 function buildModelPickerCatalog(params: {
@@ -185,14 +186,11 @@ export async function maybeHandleModelDirectiveInfo(params: {
   });
 
   if (wantsLegacyList) {
-    return {
-      text: [
-        "Model listing moved.",
-        "",
-        "Use: /models (providers) or /models <provider> (models)",
-        "Switch: /model <provider/model>",
-      ].join("\n"),
-    };
+    const reply = await resolveModelsCommandReply({
+      cfg: params.cfg,
+      commandBodyNormalized: "/models",
+    });
+    return reply ?? { text: "No models available." };
   }
 
   if (wantsSummary) {
@@ -340,42 +338,7 @@ export function resolveModelSelectionFromDirective(params: {
     }
 
     if (resolved.selection) {
-      const suggestion = `${resolved.selection.provider}/${resolved.selection.model}`;
-      const rawHasSlash = raw.includes("/");
-      const shouldAutoSelect = (() => {
-        if (!rawHasSlash) return true;
-        const slash = raw.indexOf("/");
-        if (slash <= 0) return true;
-        const rawProvider = normalizeProviderId(raw.slice(0, slash));
-        const rawFragment = raw
-          .slice(slash + 1)
-          .trim()
-          .toLowerCase();
-        if (!rawFragment) return false;
-        const resolvedProvider = normalizeProviderId(resolved.selection.provider);
-        if (rawProvider !== resolvedProvider) return false;
-        const resolvedModel = resolved.selection.model.toLowerCase();
-        return (
-          resolvedModel.startsWith(rawFragment) ||
-          resolvedModel.includes(rawFragment) ||
-          rawFragment.startsWith(resolvedModel)
-        );
-      })();
-
-      if (shouldAutoSelect) {
-        modelSelection = resolved.selection;
-      } else {
-        return {
-          errorText: [
-            `Unrecognized model: ${raw}`,
-            "",
-            `Did you mean: ${suggestion}`,
-            `Try: /model ${suggestion}`,
-            "",
-            "Browse: /models or /models <provider>",
-          ].join("\n"),
-        };
-      }
+      modelSelection = resolved.selection;
     }
   }
 

src/cli/update-cli.test.ts

@@ -4,6 +4,7 @@ import path from "node:path";
 import { beforeEach, describe, expect, it, vi } from "vitest";
 
 import type { UpdateRunResult } from "../infra/update-runner.js";
+import { parseSemver } from "../infra/runtime-guard.js";
 
 // Mock the update-runner module
 vi.mock("../infra/update-runner.js", () => ({
@@ -74,6 +75,23 @@ describe("update-cli", () => {
     });
   };
 
+  const readRepoVersion = async () => {
+    const raw = await fs.readFile(new URL("../../package.json", import.meta.url), "utf-8");
+    const parsed = JSON.parse(raw) as { version?: string };
+    if (!parsed.version) {
+      throw new Error("package.json version missing");
+    }
+    return parsed.version;
+  };
+
+  const bumpPatch = (version: string, delta: number) => {
+    const parsed = parseSemver(version);
+    if (!parsed) {
+      throw new Error(`invalid version: ${version}`);
+    }
+    return `${parsed.major}.${parsed.minor}.${Math.max(0, parsed.patch + delta)}`;
+  };
+
   beforeEach(async () => {
     vi.clearAllMocks();
     const { resolveClawdbotPackageRoot } = await import("../infra/clawdbot-root.js");
@@ -271,9 +289,12 @@ describe("update-cli", () => {
   it("falls back to latest when beta tag is older than release", async () => {
     const tempDir = await fs.mkdtemp(path.join(os.tmpdir(), "clawdbot-update-"));
     try {
+      const repoVersion = await readRepoVersion();
+      const currentVersion = bumpPatch(repoVersion, 0);
+      const latestVersion = bumpPatch(repoVersion, 1);
       await fs.writeFile(
         path.join(tempDir, "package.json"),
-        JSON.stringify({ name: "clawdbot", version: "2026.1.18-1" }),
+        JSON.stringify({ name: "clawdbot", version: currentVersion }),
         "utf-8",
       );
 
@@ -302,7 +323,7 @@ describe("update-cli", () => {
       });
       vi.mocked(resolveNpmChannelTag).mockResolvedValue({
         tag: "latest",
-        version: "2026.1.20-1",
+        version: latestVersion,
       });
       vi.mocked(runGatewayUpdate).mockResolvedValue({
         status: "ok",

src/config/schema.ts

@@ -161,6 +161,7 @@ const FIELD_LABELS: Record<string, string> = {
   "tools.exec.applyPatch.enabled": "Enable apply_patch",
   "tools.exec.applyPatch.allowModels": "apply_patch Model Allowlist",
   "tools.exec.notifyOnExit": "Exec Notify On Exit",
+  "tools.exec.approvalRunningNoticeMs": "Exec Approval Running Notice (ms)",
   "tools.exec.host": "Exec Host",
   "tools.exec.security": "Exec Security",
   "tools.exec.ask": "Exec Ask",

src/config/types.agent-defaults.ts

@@ -173,6 +173,8 @@ export type AgentDefaultsConfig = {
     };
     /** Heartbeat model override (provider/model). */
     model?: string;
+    /** Session key for heartbeat runs ("main" or explicit session key). */
+    session?: string;
     /** Delivery target (last|whatsapp|telegram|discord|slack|msteams|signal|imessage|none). */
     target?:
       | "last"

src/config/types.tools.ts

@@ -137,6 +137,8 @@ export type ExecToolConfig = {
   backgroundMs?: number;
   /** Default timeout (seconds) before auto-killing exec commands. */
   timeoutSec?: number;
+  /** Emit a running notice (ms) when approval-backed exec runs long (default: 10000, 0 = off). */
+  approvalRunningNoticeMs?: number;
   /** How long to keep finished sessions in memory (ms). */
   cleanupMs?: number;
   /** Emit a system event and heartbeat when a backgrounded exec exits. */

src/config/zod-schema.agent-runtime.ts

@@ -20,6 +20,7 @@ export const HeartbeatSchema = z
       .strict()
       .optional(),
     model: z.string().optional(),
+    session: z.string().optional(),
     includeReasoning: z.boolean().optional(),
     target: z
       .union([
@@ -260,6 +261,7 @@ export const AgentToolsSchema = z
         safeBins: z.array(z.string()).optional(),
         backgroundMs: z.number().int().positive().optional(),
         timeoutSec: z.number().int().positive().optional(),
+        approvalRunningNoticeMs: z.number().int().nonnegative().optional(),
         cleanupMs: z.number().int().positive().optional(),
         notifyOnExit: z.boolean().optional(),
         applyPatch: z

src/gateway/exec-approval-manager.ts

@@ -33,11 +33,15 @@ type PendingEntry = {
 export class ExecApprovalManager {
   private pending = new Map<string, PendingEntry>();
 
-  create(request: ExecApprovalRequestPayload, timeoutMs: number): ExecApprovalRecord {
+  create(
+    request: ExecApprovalRequestPayload,
+    timeoutMs: number,
+    id?: string | null,
+  ): ExecApprovalRecord {
     const now = Date.now();
-    const id = randomUUID();
+    const resolvedId = id && id.trim().length > 0 ? id.trim() : randomUUID();
     const record: ExecApprovalRecord = {
-      id,
+      id: resolvedId,
       request,
       createdAtMs: now,
       expiresAtMs: now + timeoutMs,

src/gateway/protocol/schema/exec-approvals.ts

@@ -89,6 +89,7 @@ export const ExecApprovalsNodeSetParamsSchema = Type.Object(
 
 export const ExecApprovalRequestParamsSchema = Type.Object(
   {
+    id: Type.Optional(NonEmptyString),
     command: NonEmptyString,
     cwd: Type.Optional(Type.String()),
     host: Type.Optional(Type.String()),

src/gateway/server-methods/exec-approval.test.ts

@@ -60,4 +60,120 @@ describe("exec approval handlers", () => {
     );
     expect(broadcasts.some((entry) => entry.event === "exec.approval.resolved")).toBe(true);
   });
+
+  it("accepts explicit approval ids", async () => {
+    const manager = new ExecApprovalManager();
+    const handlers = createExecApprovalHandlers(manager);
+    const broadcasts: Array<{ event: string; payload: unknown }> = [];
+
+    const respond = vi.fn();
+    const context = {
+      broadcast: (event: string, payload: unknown) => {
+        broadcasts.push({ event, payload });
+      },
+    };
+
+    const requestPromise = handlers["exec.approval.request"]({
+      params: {
+        id: "approval-123",
+        command: "echo ok",
+        cwd: "/tmp",
+        host: "gateway",
+        timeoutMs: 2000,
+      },
+      respond,
+      context: context as unknown as Parameters<
+        (typeof handlers)["exec.approval.request"]
+      >[0]["context"],
+      client: null,
+      req: { id: "req-1", type: "req", method: "exec.approval.request" },
+      isWebchatConnect: noop,
+    });
+
+    const requested = broadcasts.find((entry) => entry.event === "exec.approval.requested");
+    const id = (requested?.payload as { id?: string })?.id ?? "";
+    expect(id).toBe("approval-123");
+
+    const resolveRespond = vi.fn();
+    await handlers["exec.approval.resolve"]({
+      params: { id, decision: "allow-once" },
+      respond: resolveRespond,
+      context: context as unknown as Parameters<
+        (typeof handlers)["exec.approval.resolve"]
+      >[0]["context"],
+      client: { connect: { client: { id: "cli", displayName: "CLI" } } },
+      req: { id: "req-2", type: "req", method: "exec.approval.resolve" },
+      isWebchatConnect: noop,
+    });
+
+    await requestPromise;
+    expect(respond).toHaveBeenCalledWith(
+      true,
+      expect.objectContaining({ id: "approval-123", decision: "allow-once" }),
+      undefined,
+    );
+  });
+
+  it("rejects duplicate approval ids", async () => {
+    const manager = new ExecApprovalManager();
+    const handlers = createExecApprovalHandlers(manager);
+    const respondA = vi.fn();
+    const respondB = vi.fn();
+    const broadcasts: Array<{ event: string; payload: unknown }> = [];
+    const context = {
+      broadcast: (event: string, payload: unknown) => {
+        broadcasts.push({ event, payload });
+      },
+    };
+
+    const requestPromise = handlers["exec.approval.request"]({
+      params: {
+        id: "dup-1",
+        command: "echo ok",
+      },
+      respond: respondA,
+      context: context as unknown as Parameters<
+        (typeof handlers)["exec.approval.request"]
+      >[0]["context"],
+      client: null,
+      req: { id: "req-1", type: "req", method: "exec.approval.request" },
+      isWebchatConnect: noop,
+    });
+
+    await handlers["exec.approval.request"]({
+      params: {
+        id: "dup-1",
+        command: "echo again",
+      },
+      respond: respondB,
+      context: context as unknown as Parameters<
+        (typeof handlers)["exec.approval.request"]
+      >[0]["context"],
+      client: null,
+      req: { id: "req-2", type: "req", method: "exec.approval.request" },
+      isWebchatConnect: noop,
+    });
+
+    expect(respondB).toHaveBeenCalledWith(
+      false,
+      undefined,
+      expect.objectContaining({ message: "approval id already pending" }),
+    );
+
+    const requested = broadcasts.find((entry) => entry.event === "exec.approval.requested");
+    const id = (requested?.payload as { id?: string })?.id ?? "";
+    const resolveRespond = vi.fn();
+    await handlers["exec.approval.resolve"]({
+      params: { id, decision: "deny" },
+      respond: resolveRespond,
+      context: context as unknown as Parameters<
+        (typeof handlers)["exec.approval.resolve"]
+      >[0]["context"],
+      client: { connect: { client: { id: "cli", displayName: "CLI" } } },
+      req: { id: "req-3", type: "req", method: "exec.approval.resolve" },
+      isWebchatConnect: noop,
+    });
+
+    await requestPromise;
+  });
 });

src/gateway/server-methods/exec-approval.ts

@@ -26,6 +26,7 @@ export function createExecApprovalHandlers(manager: ExecApprovalManager): Gatewa
         return;
       }
       const p = params as {
+        id?: string;
         command: string;
         cwd?: string;
         host?: string;
@@ -37,6 +38,15 @@ export function createExecApprovalHandlers(manager: ExecApprovalManager): Gatewa
         timeoutMs?: number;
       };
       const timeoutMs = typeof p.timeoutMs === "number" ? p.timeoutMs : 120_000;
+      const explicitId = typeof p.id === "string" && p.id.trim().length > 0 ? p.id.trim() : null;
+      if (explicitId && manager.getSnapshot(explicitId)) {
+        respond(
+          false,
+          undefined,
+          errorShape(ErrorCodes.INVALID_REQUEST, "approval id already pending"),
+        );
+        return;
+      }
       const request = {
         command: p.command,
         cwd: p.cwd ?? null,
@@ -47,7 +57,7 @@ export function createExecApprovalHandlers(manager: ExecApprovalManager): Gatewa
         resolvedPath: p.resolvedPath ?? null,
         sessionKey: p.sessionKey ?? null,
       };
-      const record = manager.create(request, timeoutMs);
+      const record = manager.create(request, timeoutMs, explicitId);
       context.broadcast(
         "exec.approval.requested",
         {

src/infra/exec-approvals.test.ts

@@ -17,6 +17,13 @@ import {
   type ExecAllowlistEntry,
 } from "./exec-approvals.js";
 
+function makePathEnv(binDir: string): NodeJS.ProcessEnv {
+  if (process.platform !== "win32") {
+    return { PATH: binDir };
+  }
+  return { PATH: binDir, PATHEXT: ".EXE;.CMD;.BAT;.COM" };
+}
+
 function makeTempDir() {
   return fs.mkdtempSync(path.join(os.tmpdir(), "clawdbot-exec-approvals-"));
 }
@@ -72,12 +79,13 @@ describe("exec approvals command resolution", () => {
     const dir = makeTempDir();
     const binDir = path.join(dir, "bin");
     fs.mkdirSync(binDir, { recursive: true });
-    const exe = path.join(binDir, "rg");
+    const exeName = process.platform === "win32" ? "rg.exe" : "rg";
+    const exe = path.join(binDir, exeName);
     fs.writeFileSync(exe, "");
     fs.chmodSync(exe, 0o755);
-    const res = resolveCommandResolution("rg -n foo", undefined, { PATH: binDir });
+    const res = resolveCommandResolution("rg -n foo", undefined, makePathEnv(binDir));
     expect(res?.resolvedPath).toBe(exe);
-    expect(res?.executableName).toBe("rg");
+    expect(res?.executableName).toBe(exeName);
   });
 
   it("resolves relative paths against cwd", () => {
@@ -127,13 +135,14 @@ describe("exec approvals safe bins", () => {
     const dir = makeTempDir();
     const binDir = path.join(dir, "bin");
     fs.mkdirSync(binDir, { recursive: true });
-    const exe = path.join(binDir, "jq");
+    const exeName = process.platform === "win32" ? "jq.exe" : "jq";
+    const exe = path.join(binDir, exeName);
     fs.writeFileSync(exe, "");
     fs.chmodSync(exe, 0o755);
     const res = analyzeShellCommand({
       command: "jq .foo",
       cwd: dir,
-      env: { PATH: binDir },
+      env: makePathEnv(binDir),
     });
     expect(res.ok).toBe(true);
     const segment = res.segments[0];
@@ -150,7 +159,8 @@ describe("exec approvals safe bins", () => {
     const dir = makeTempDir();
     const binDir = path.join(dir, "bin");
     fs.mkdirSync(binDir, { recursive: true });
-    const exe = path.join(binDir, "jq");
+    const exeName = process.platform === "win32" ? "jq.exe" : "jq";
+    const exe = path.join(binDir, exeName);
     fs.writeFileSync(exe, "");
     fs.chmodSync(exe, 0o755);
     const file = path.join(dir, "secret.json");
@@ -158,7 +168,7 @@ describe("exec approvals safe bins", () => {
     const res = analyzeShellCommand({
       command: "jq .foo secret.json",
       cwd: dir,
-      env: { PATH: binDir },
+      env: makePathEnv(binDir),
     });
     expect(res.ok).toBe(true);
     const segment = res.segments[0];

src/infra/exec-approvals.ts

@@ -660,7 +660,11 @@ export function isSafeBinUsage(params: {
   if (params.safeBins.size === 0) return false;
   const resolution = params.resolution;
   const execName = resolution?.executableName?.toLowerCase();
-  if (!execName || !params.safeBins.has(execName)) return false;
+  if (!execName) return false;
+  const matchesSafeBin =
+    params.safeBins.has(execName) ||
+    (process.platform === "win32" && params.safeBins.has(path.parse(execName).name));
+  if (!matchesSafeBin) return false;
   if (!resolution?.resolvedPath) return false;
   const cwd = params.cwd ?? process.cwd();
   const exists = params.fileExists ?? defaultFileExists;

src/infra/heartbeat-runner.respects-ackmaxchars-heartbeat-acks.test.ts

@@ -41,7 +41,6 @@ describe("resolveHeartbeatIntervalMs", () => {
             heartbeat: {
               every: "5m",
               target: "whatsapp",
-              to: "+1555",
               ackMaxChars: 0,
             },
           },
@@ -58,6 +57,7 @@ describe("resolveHeartbeatIntervalMs", () => {
             [sessionKey]: {
               sessionId: "sid",
               updatedAt: Date.now(),
+              lastChannel: "whatsapp",
               lastProvider: "whatsapp",
               lastTo: "+1555",
             },
@@ -102,7 +102,6 @@ describe("resolveHeartbeatIntervalMs", () => {
             heartbeat: {
               every: "5m",
               target: "whatsapp",
-              to: "+1555",
             },
           },
         },
@@ -118,6 +117,7 @@ describe("resolveHeartbeatIntervalMs", () => {
             [sessionKey]: {
               sessionId: "sid",
               updatedAt: Date.now(),
+              lastChannel: "whatsapp",
               lastProvider: "whatsapp",
               lastTo: "+1555",
             },
@@ -164,7 +164,6 @@ describe("resolveHeartbeatIntervalMs", () => {
             heartbeat: {
               every: "5m",
               target: "whatsapp",
-              to: "+1555",
             },
           },
         },
@@ -180,6 +179,7 @@ describe("resolveHeartbeatIntervalMs", () => {
             [sessionKey]: {
               sessionId: "sid",
               updatedAt: originalUpdatedAt,
+              lastChannel: "whatsapp",
               lastProvider: "whatsapp",
               lastTo: "+1555",
             },
@@ -231,7 +231,7 @@ describe("resolveHeartbeatIntervalMs", () => {
       const cfg: ClawdbotConfig = {
         agents: {
           defaults: {
-            heartbeat: { every: "5m", target: "whatsapp", to: "+1555" },
+            heartbeat: { every: "5m", target: "whatsapp" },
           },
         },
         channels: { whatsapp: { allowFrom: ["*"] } },
@@ -246,6 +246,7 @@ describe("resolveHeartbeatIntervalMs", () => {
             [sessionKey]: {
               sessionId: "sid",
               updatedAt: Date.now(),
+              lastChannel: "whatsapp",
               lastProvider: "whatsapp",
               lastTo: "+1555",
             },
@@ -291,7 +292,7 @@ describe("resolveHeartbeatIntervalMs", () => {
       const cfg: ClawdbotConfig = {
         agents: {
           defaults: {
-            heartbeat: { every: "5m", target: "telegram", to: "123456" },
+            heartbeat: { every: "5m", target: "telegram" },
           },
         },
         channels: { telegram: { botToken: "test-bot-token-123" } },
@@ -306,6 +307,7 @@ describe("resolveHeartbeatIntervalMs", () => {
             [sessionKey]: {
               sessionId: "sid",
               updatedAt: Date.now(),
+              lastChannel: "telegram",
               lastProvider: "telegram",
               lastTo: "123456",
             },
@@ -357,7 +359,7 @@ describe("resolveHeartbeatIntervalMs", () => {
       const cfg: ClawdbotConfig = {
         agents: {
           defaults: {
-            heartbeat: { every: "5m", target: "telegram", to: "123456" },
+            heartbeat: { every: "5m", target: "telegram" },
           },
         },
         channels: {
@@ -378,6 +380,7 @@ describe("resolveHeartbeatIntervalMs", () => {
             [sessionKey]: {
               sessionId: "sid",
               updatedAt: Date.now(),
+              lastChannel: "telegram",
               lastProvider: "telegram",
               lastTo: "123456",
             },

src/infra/heartbeat-runner.returns-default-unset.test.ts

@@ -11,6 +11,7 @@ import {
   resolveMainSessionKey,
   resolveStorePath,
 } from "../config/sessions.js";
+import { buildAgentPeerSessionKey } from "../routing/session-key.js";
 import {
   isHeartbeatEnabledForAgent,
   resolveHeartbeatIntervalMs,
@@ -332,7 +333,7 @@ describe("runHeartbeatOnce", () => {
       const cfg: ClawdbotConfig = {
         agents: {
           defaults: {
-            heartbeat: { every: "5m", target: "whatsapp", to: "+1555" },
+            heartbeat: { every: "5m", target: "whatsapp" },
           },
         },
         channels: { whatsapp: { allowFrom: ["*"] } },
@@ -395,7 +396,7 @@ describe("runHeartbeatOnce", () => {
             { id: "main", default: true },
             {
               id: "ops",
-              heartbeat: { every: "5m", target: "whatsapp", to: "+1555", prompt: "Ops check" },
+              heartbeat: { every: "5m", target: "whatsapp", prompt: "Ops check" },
             },
           ],
         },
@@ -451,6 +452,88 @@ describe("runHeartbeatOnce", () => {
     }
   });
 
+  it("runs heartbeats in the explicit session key when configured", async () => {
+    const tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), "clawdbot-hb-"));
+    const storePath = path.join(tmpDir, "sessions.json");
+    const replySpy = vi.spyOn(replyModule, "getReplyFromConfig");
+    try {
+      const groupId = "120363401234567890@g.us";
+      const cfg: ClawdbotConfig = {
+        agents: {
+          defaults: {
+            heartbeat: {
+              every: "5m",
+              target: "last",
+            },
+          },
+        },
+        channels: { whatsapp: { allowFrom: ["*"] } },
+        session: { store: storePath },
+      };
+      const mainSessionKey = resolveMainSessionKey(cfg);
+      const agentId = resolveAgentIdFromSessionKey(mainSessionKey);
+      const groupSessionKey = buildAgentPeerSessionKey({
+        agentId,
+        channel: "whatsapp",
+        peerKind: "group",
+        peerId: groupId,
+      });
+      if (cfg.agents?.defaults?.heartbeat) {
+        cfg.agents.defaults.heartbeat.session = groupSessionKey;
+      }
+
+      await fs.writeFile(
+        storePath,
+        JSON.stringify(
+          {
+            [mainSessionKey]: {
+              sessionId: "sid-main",
+              updatedAt: Date.now(),
+              lastChannel: "whatsapp",
+              lastTo: "+1555",
+            },
+            [groupSessionKey]: {
+              sessionId: "sid-group",
+              updatedAt: Date.now() + 10_000,
+              lastChannel: "whatsapp",
+              lastTo: groupId,
+            },
+          },
+          null,
+          2,
+        ),
+      );
+
+      replySpy.mockResolvedValue([{ text: "Group alert" }]);
+      const sendWhatsApp = vi.fn().mockResolvedValue({
+        messageId: "m1",
+        toJid: "jid",
+      });
+
+      await runHeartbeatOnce({
+        cfg,
+        deps: {
+          sendWhatsApp,
+          getQueueSize: () => 0,
+          nowMs: () => 0,
+          webAuthExists: async () => true,
+          hasActiveWebListener: () => true,
+        },
+      });
+
+      expect(sendWhatsApp).toHaveBeenCalledTimes(1);
+      expect(sendWhatsApp).toHaveBeenCalledWith(groupId, "Group alert", expect.any(Object));
+      expect(replySpy).toHaveBeenCalledWith(
+        expect.objectContaining({ SessionKey: groupSessionKey }),
+        { isHeartbeat: true },
+        cfg,
+      );
+    } finally {
+      replySpy.mockRestore();
+      await fs.rm(tmpDir, { recursive: true, force: true });
+    }
+  });
+
   it("suppresses duplicate heartbeat payloads within 24h", async () => {
     const tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), "clawdbot-hb-"));
     const storePath = path.join(tmpDir, "sessions.json");
@@ -459,7 +542,7 @@ describe("runHeartbeatOnce", () => {
       const cfg: ClawdbotConfig = {
         agents: {
           defaults: {
-            heartbeat: { every: "5m", target: "whatsapp", to: "+1555" },
+            heartbeat: { every: "5m", target: "whatsapp" },
           },
         },
         channels: { whatsapp: { allowFrom: ["*"] } },
@@ -517,7 +600,6 @@ describe("runHeartbeatOnce", () => {
             heartbeat: {
               every: "5m",
               target: "whatsapp",
-              to: "+1555",
               includeReasoning: true,
             },
           },
@@ -534,6 +616,7 @@ describe("runHeartbeatOnce", () => {
             [sessionKey]: {
               sessionId: "sid",
               updatedAt: Date.now(),
+              lastChannel: "whatsapp",
               lastProvider: "whatsapp",
               lastTo: "+1555",
             },
@@ -588,7 +671,6 @@ describe("runHeartbeatOnce", () => {
             heartbeat: {
               every: "5m",
               target: "whatsapp",
-              to: "+1555",
               includeReasoning: true,
             },
           },
@@ -605,6 +687,7 @@ describe("runHeartbeatOnce", () => {
             [sessionKey]: {
               sessionId: "sid",
               updatedAt: Date.now(),
+              lastChannel: "whatsapp",
               lastProvider: "whatsapp",
               lastTo: "+1555",
             },
@@ -672,6 +755,7 @@ describe("runHeartbeatOnce", () => {
             [sessionKey]: {
               sessionId: "sid",
               updatedAt: Date.now(),
+              lastChannel: "whatsapp",
               lastProvider: "whatsapp",
               lastTo: "+1555",
             },

src/infra/heartbeat-runner.ts

@@ -15,7 +15,9 @@ import { parseDurationMs } from "../cli/parse-duration.js";
 import type { ClawdbotConfig } from "../config/config.js";
 import { loadConfig } from "../config/config.js";
 import {
+  canonicalizeMainSessionAlias,
   loadSessionStore,
+  resolveAgentIdFromSessionKey,
   resolveAgentMainSessionKey,
   resolveStorePath,
   saveSessionStore,
@@ -27,7 +29,7 @@ import { createSubsystemLogger } from "../logging/subsystem.js";
 import { getQueueSize } from "../process/command-queue.js";
 import { CommandLane } from "../process/lanes.js";
 import { defaultRuntime, type RuntimeEnv } from "../runtime.js";
-import { normalizeAgentId } from "../routing/session-key.js";
+import { normalizeAgentId, toAgentStoreSessionKey } from "../routing/session-key.js";
 import { emitHeartbeatEvent } from "./heartbeat-events.js";
 import {
   type HeartbeatRunResult,
@@ -286,17 +288,53 @@ function resolveHeartbeatAckMaxChars(cfg: ClawdbotConfig, heartbeat?: HeartbeatC
   );
 }
 
-function resolveHeartbeatSession(cfg: ClawdbotConfig, agentId?: string) {
+function resolveHeartbeatSession(
+  cfg: ClawdbotConfig,
+  agentId?: string,
+  heartbeat?: HeartbeatConfig,
+) {
   const sessionCfg = cfg.session;
   const scope = sessionCfg?.scope ?? "per-sender";
   const resolvedAgentId = normalizeAgentId(agentId ?? resolveDefaultAgentId(cfg));
-  const sessionKey =
+  const mainSessionKey =
     scope === "global" ? "global" : resolveAgentMainSessionKey({ cfg, agentId: resolvedAgentId });
   const storeAgentId = scope === "global" ? resolveDefaultAgentId(cfg) : resolvedAgentId;
   const storePath = resolveStorePath(sessionCfg?.store, { agentId: storeAgentId });
   const store = loadSessionStore(storePath);
-  const entry = store[sessionKey];
-  return { sessionKey, storePath, store, entry };
+  const mainEntry = store[mainSessionKey];
+
+  if (scope === "global") {
+    return { sessionKey: mainSessionKey, storePath, store, entry: mainEntry };
+  }
+
+  const trimmed = heartbeat?.session?.trim() ?? "";
+  if (!trimmed) {
+    return { sessionKey: mainSessionKey, storePath, store, entry: mainEntry };
+  }
+
+  const normalized = trimmed.toLowerCase();
+  if (normalized === "main" || normalized === "global") {
+    return { sessionKey: mainSessionKey, storePath, store, entry: mainEntry };
+  }
+
+  const candidate = toAgentStoreSessionKey({
+    agentId: resolvedAgentId,
+    requestKey: trimmed,
+    mainKey: cfg.session?.mainKey,
+  });
+  const canonical = canonicalizeMainSessionAlias({
+    cfg,
+    agentId: resolvedAgentId,
+    sessionKey: candidate,
+  });
+  if (canonical !== "global") {
+    const sessionAgentId = resolveAgentIdFromSessionKey(canonical);
+    if (sessionAgentId === normalizeAgentId(resolvedAgentId)) {
+      return { sessionKey: canonical, storePath, store, entry: store[canonical] };
+    }
+  }
+
+  return { sessionKey: mainSessionKey, storePath, store, entry: mainEntry };
 }
 
 function resolveHeartbeatReplyPayload(
@@ -427,7 +465,7 @@ export async function runHeartbeatOnce(opts: {
     return { status: "skipped", reason: "requests-in-flight" };
   }
 
-  const { entry, sessionKey, storePath } = resolveHeartbeatSession(cfg, agentId);
+  const { entry, sessionKey, storePath } = resolveHeartbeatSession(cfg, agentId, heartbeat);
   const previousUpdatedAt = entry?.updatedAt;
   const delivery = resolveHeartbeatDeliveryTarget({ cfg, entry, heartbeat });
   const lastChannel = delivery.lastChannel;

src/infra/update-check.test.ts

@@ -28,20 +28,20 @@ describe("resolveNpmChannelTag", () => {
   });
 
   it("falls back to latest when beta is older", async () => {
-    versionByTag.beta = "2026.1.19-beta.1";
-    versionByTag.latest = "2026.1.20-1";
+    versionByTag.beta = "1.0.0-beta.1";
+    versionByTag.latest = "1.0.1-1";
 
     const resolved = await resolveNpmChannelTag({ channel: "beta", timeoutMs: 1000 });
 
-    expect(resolved).toEqual({ tag: "latest", version: "2026.1.20-1" });
+    expect(resolved).toEqual({ tag: "latest", version: "1.0.1-1" });
   });
 
   it("keeps beta when beta is not older", async () => {
-    versionByTag.beta = "2026.1.20-beta.1";
-    versionByTag.latest = "2026.1.20-1";
+    versionByTag.beta = "1.0.2-beta.1";
+    versionByTag.latest = "1.0.1-1";
 
     const resolved = await resolveNpmChannelTag({ channel: "beta", timeoutMs: 1000 });
 
-    expect(resolved).toEqual({ tag: "beta", version: "2026.1.20-beta.1" });
+    expect(resolved).toEqual({ tag: "beta", version: "1.0.2-beta.1" });
   });
 });

src/infra/update-runner.test.ts

@@ -96,8 +96,8 @@ describe("runGatewayUpdate", () => {
       JSON.stringify({ name: "clawdbot", version: "1.0.0", packageManager: "pnpm@8.0.0" }),
       "utf-8",
     );
-    const stableTag = "v2026.1.20-1";
-    const betaTag = "v2026.1.19-beta.2";
+    const stableTag = "v1.0.1-1";
+    const betaTag = "v1.0.0-beta.2";
     const { runner, calls } = createRunner({
       [`git -C ${tempDir} rev-parse --show-toplevel`]: { stdout: tempDir },
       [`git -C ${tempDir} rev-parse HEAD`]: { stdout: "abc123" },

src/node-host/runner.ts

@@ -57,6 +57,7 @@ type SystemRunParams = {
   sessionKey?: string | null;
   approved?: boolean | null;
   approvalDecision?: string | null;
+  runId?: string | null;
 };
 
 type SystemWhichParams = {
@@ -583,7 +584,7 @@ async function handleInvoke(
   const ask = approvals.agent.ask;
   const autoAllowSkills = approvals.agent.autoAllowSkills;
   const sessionKey = params.sessionKey?.trim() || "node";
-  const runId = crypto.randomUUID();
+  const runId = params.runId?.trim() || crypto.randomUUID();
   const env = sanitizeEnv(params.env ?? undefined);
   const analysis = rawCommand
     ? analyzeShellCommand({ command: rawCommand, cwd: params.cwd ?? undefined, env })
@@ -803,17 +804,6 @@ async function handleInvoke(
     return;
   }
 
-  await sendNodeEvent(
-    client,
-    "exec.started",
-    buildExecEventPayload({
-      sessionKey,
-      runId,
-      host: "node",
-      command: cmdText,
-    }),
-  );
-
   const result = await runCommand(
     argv,
     params.cwd?.trim() || undefined,