fix: enforce strict exec approval optionals (#1414) (thanks @czekaj)

TypeBox Type.Optional(Type.String()) accepts string|undefined but NOT null.
Discord exec was failing with 'resolvedPath must be string' because callers
passed null explicitly. Web UI worked because it skipped the approval request.

Fixes exec approval validation error in Discord-triggered sessions.

AGENTS.md

@@ -29,6 +29,7 @@
 - Prefer Bun for TypeScript execution (scripts, dev, tests): `bun <file.ts>` / `bunx <tool>`.
 - Run CLI in dev: `pnpm clawdbot ...` (bun) or `pnpm dev`.
 - Node remains supported for running built output (`dist/*`) and production installs.
+- Mac packaging (dev): `scripts/package-mac-app.sh` defaults to current arch. Release checklist: `docs/platforms/mac/release.md`.
 - Type-check/build: `pnpm build` (tsc)
 - Lint/format: `pnpm lint` (oxlint), `pnpm format` (oxfmt)
 - Tests: `pnpm test` (vitest); coverage: `pnpm test:coverage`

CHANGELOG.md

@@ -2,32 +2,55 @@
 
 Docs: https://docs.clawd.bot
 
+## 2026.1.22
+
+### Changes
+- Highlight: Lobster optional plugin tool for typed workflows + approval gates. https://docs.clawd.bot/tools/lobster
+- 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
+- Config: avoid stack traces for invalid configs and log the config path.
+- Doctor: warn when gateway.mode is unset with configure/config guidance.
+- macOS: include Textual syntax highlighting resources in packaged app to prevent chat crashes. (#1362)
+- Exec approvals: send optional approval params as undefined instead of null. (#1414) Thanks @czekaj.
+- UI: refresh debug panel on route-driven tab changes. (#1373) Thanks @yazinsai.
+
 ## 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.
+- Exec approvals: allowlist matches resolved binary paths only, add safe stdin-only bins, and tighten allowlist shell parsing.
 - Nodes: expose node PATH in status/describe and bootstrap PATH for node-host execution.
 - CLI: flatten node service commands under `clawdbot node` and remove `service node` docs.
 - CLI: move gateway service commands under `clawdbot gateway` and add `gateway probe` for reachability.
 - Sessions: add per-channel reset overrides via `session.resetByChannel`. (#1353) Thanks @cash-echo-bot.
 
+### Breaking
+- **BREAKING:** Control UI now rejects insecure HTTP without device identity by default. Use HTTPS (Tailscale Serve) or set `gateway.controlUi.allowInsecureAuth: true` to allow token-only auth. https://docs.clawd.bot/web/control-ui#insecure-http
+
 ### 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 (`*`).
 - macOS: allow SSH agent auth when no identity file is set. (#1384) Thanks @ameno-.
+- Gateway: prevent multiple gateways from sharing the same config/state at once (singleton lock).
 - UI: remove the chat stop button and keep the composer aligned to the bottom edge.
 - Typing: start instant typing indicators at run start so DMs and mentions show immediately.
 - Configure: restrict the model allowlist picker to OAuth-compatible Anthropic models and preselect Opus 4.5.
 - Configure: seed model fallbacks from the allowlist selection when multiple models are chosen.
 - Model picker: list the full catalog when no model allowlist is configured.
-- Chat: include configured defaults/providers in `/models` output and normalize all-mode paging. (#1398) Thanks @vignesh07.
 - Discord: honor wildcard channel configs via shared match helpers. (#1334) Thanks @pvoo.
 - BlueBubbles: resolve short message IDs safely and expose full IDs in templates. (#1387) Thanks @tyler6204.
 - Infra: preserve fetch helper methods when wrapping abort signals. (#1387)
+- macOS: default distribution packaging to universal binaries. (#1396) Thanks @JustYannicc.
 
 ## 2026.1.20
 

README.md

@@ -471,6 +471,9 @@ by Peter Steinberger and the community.
 See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines, maintainers, and how to submit PRs.  
 AI/vibe-coded PRs welcome! 🤖
 
+Special thanks to [Mario Zechner](https://mariozechner.at/) for his support and for
+[pi-mono](https://github.com/badlogic/pi-mono).
+
 Thanks to all clawtributors:
 
 <p align="left">

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(
@@ -554,6 +556,30 @@ enum ExecCommandFormatter {
     }
 }
 
+enum ExecApprovalHelpers {
+    static func parseDecision(_ raw: String?) -> ExecApprovalDecision? {
+        let trimmed = raw?.trimmingCharacters(in: .whitespacesAndNewlines) ?? ""
+        guard !trimmed.isEmpty else { return nil }
+        return ExecApprovalDecision(rawValue: trimmed)
+    }
+
+    static func requiresAsk(
+        ask: ExecAsk,
+        security: ExecSecurity,
+        allowlistMatch: ExecAllowlistEntry?,
+        skillAllow: Bool) -> Bool
+    {
+        if ask == .always { return true }
+        if ask == .onMiss, security == .allowlist, allowlistMatch == nil, !skillAllow { return true }
+        return false
+    }
+
+    static func allowlistPattern(command: [String], resolution: ExecCommandResolution?) -> String? {
+        let pattern = resolution?.resolvedPath ?? resolution?.rawExecutable ?? command.first ?? ""
+        return pattern.isEmpty ? nil : pattern
+    }
+}
+
 enum ExecAllowlistMatcher {
     static func match(entries: [ExecAllowlistEntry], resolution: ExecCommandResolution?) -> ExecAllowlistEntry? {
         guard let resolution, !entries.isEmpty else { return nil }

apps/macos/Sources/Clawdbot/ExecApprovalsSocket.swift

@@ -314,7 +314,7 @@ private enum ExecHostExecutor {
         }
 
         var approvedByAsk = approvalDecision != nil
-        if self.requiresAsk(
+        if ExecApprovalHelpers.requiresAsk(
             ask: context.ask,
             security: context.security,
             allowlistMatch: context.allowlistMatch,
@@ -417,36 +417,20 @@ private enum ExecHostExecutor {
             skillAllow: skillAllow)
     }
 
-    private static func requiresAsk(
-        ask: ExecAsk,
-        security: ExecSecurity,
-        allowlistMatch: ExecAllowlistEntry?,
-        skillAllow: Bool) -> Bool
-    {
-        if ask == .always { return true }
-        if ask == .onMiss, security == .allowlist, allowlistMatch == nil, !skillAllow { return true }
-        return false
-    }
-
     private static func persistAllowlistEntry(
         decision: ExecApprovalDecision?,
         context: ExecApprovalContext)
     {
         guard decision == .allowAlways, context.security == .allowlist else { return }
-        guard let pattern = self.allowlistPattern(command: context.command, resolution: context.resolution) else {
+        guard let pattern = ExecApprovalHelpers.allowlistPattern(
+            command: context.command,
+            resolution: context.resolution)
+        else {
             return
         }
         ExecApprovalsStore.addAllowlistEntry(agentId: context.trimmedAgent, pattern: pattern)
     }
 
-    private static func allowlistPattern(
-        command: [String],
-        resolution: ExecCommandResolution?) -> String?
-    {
-        let pattern = resolution?.resolvedPath ?? resolution?.rawExecutable ?? command.first ?? ""
-        return pattern.isEmpty ? nil : pattern
-    }
-
     private static func ensureScreenRecordingAccess(_ needsScreenRecording: Bool?) async -> ExecHostResponse? {
         guard needsScreenRecording == true else { return nil }
         let authorized = await PermissionManager

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,26 +480,26 @@ actor MacNodeRuntime {
                 message: "SYSTEM_RUN_DISABLED: security=deny")
         }
 
-        let requiresAsk: Bool = {
-            if ask == .always { return true }
-            if ask == .onMiss, security == .allowlist, allowlistMatch == nil, !skillAllow { return true }
-            return false
-        }()
-
-        let approvedByAsk = params.approved == true
-        if requiresAsk, !approvedByAsk {
-            await self.emitExecEvent(
-                "exec.denied",
-                payload: ExecEventPayload(
-                    sessionKey: sessionKey,
-                    runId: runId,
-                    host: "node",
-                    command: displayCommand,
-                    reason: "approval-required"))
-            return Self.errorResponse(
-                req,
-                code: .unavailable,
-                message: "SYSTEM_RUN_DENIED: approval required")
+        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)
+        {
+            ExecApprovalsStore.addAllowlistEntry(agentId: agentId, pattern: pattern)
         }
 
         if security == .allowlist, allowlistMatch == nil, !skillAllow, !approvedByAsk {
@@ -619,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

@@ -18,6 +18,7 @@ public struct ConnectParams: Codable, Sendable {
     public let caps: [String]?
     public let commands: [String]?
     public let permissions: [String: AnyCodable]?
+    public let pathenv: String?
     public let role: String?
     public let scopes: [String]?
     public let device: [String: AnyCodable]?
@@ -32,6 +33,7 @@ public struct ConnectParams: Codable, Sendable {
         caps: [String]?,
         commands: [String]?,
         permissions: [String: AnyCodable]?,
+        pathenv: String?,
         role: String?,
         scopes: [String]?,
         device: [String: AnyCodable]?,
@@ -45,6 +47,7 @@ public struct ConnectParams: Codable, Sendable {
         self.caps = caps
         self.commands = commands
         self.permissions = permissions
+        self.pathenv = pathenv
         self.role = role
         self.scopes = scopes
         self.device = device
@@ -59,6 +62,7 @@ public struct ConnectParams: Codable, Sendable {
         case caps
         case commands
         case permissions
+        case pathenv = "pathEnv"
         case role
         case scopes
         case device
@@ -1904,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?
@@ -1915,6 +1920,7 @@ public struct ExecApprovalRequestParams: Codable, Sendable {
     public let timeoutms: Int?
 
     public init(
+        id: String?,
         command: String,
         cwd: String?,
         host: String?,
@@ -1925,6 +1931,7 @@ public struct ExecApprovalRequestParams: Codable, Sendable {
         sessionkey: String?,
         timeoutms: Int?
     ) {
+        self.id = id
         self.command = command
         self.cwd = cwd
         self.host = host
@@ -1936,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/ExecApprovalHelpersTests.swift

@@ -0,0 +1,60 @@
+import Foundation
+import Testing
+@testable import Clawdbot
+
+@Suite struct ExecApprovalHelpersTests {
+    @Test func parseDecisionTrimsAndRejectsInvalid() {
+        #expect(ExecApprovalHelpers.parseDecision("allow-once") == .allowOnce)
+        #expect(ExecApprovalHelpers.parseDecision(" allow-always ") == .allowAlways)
+        #expect(ExecApprovalHelpers.parseDecision("deny") == .deny)
+        #expect(ExecApprovalHelpers.parseDecision("") == nil)
+        #expect(ExecApprovalHelpers.parseDecision("nope") == nil)
+    }
+
+    @Test func allowlistPatternPrefersResolution() {
+        let resolved = ExecCommandResolution(
+            rawExecutable: "rg",
+            resolvedPath: "/opt/homebrew/bin/rg",
+            executableName: "rg",
+            cwd: nil)
+        #expect(ExecApprovalHelpers.allowlistPattern(command: ["rg"], resolution: resolved) == resolved.resolvedPath)
+
+        let rawOnly = ExecCommandResolution(
+            rawExecutable: "rg",
+            resolvedPath: nil,
+            executableName: "rg",
+            cwd: nil)
+        #expect(ExecApprovalHelpers.allowlistPattern(command: ["rg"], resolution: rawOnly) == "rg")
+        #expect(ExecApprovalHelpers.allowlistPattern(command: ["rg"], resolution: nil) == "rg")
+        #expect(ExecApprovalHelpers.allowlistPattern(command: [], resolution: nil) == nil)
+    }
+
+    @Test func requiresAskMatchesPolicy() {
+        let entry = ExecAllowlistEntry(pattern: "/bin/ls", lastUsedAt: nil, lastUsedCommand: nil, lastResolvedPath: nil)
+        #expect(ExecApprovalHelpers.requiresAsk(
+            ask: .always,
+            security: .deny,
+            allowlistMatch: nil,
+            skillAllow: false))
+        #expect(ExecApprovalHelpers.requiresAsk(
+            ask: .onMiss,
+            security: .allowlist,
+            allowlistMatch: nil,
+            skillAllow: false))
+        #expect(!ExecApprovalHelpers.requiresAsk(
+            ask: .onMiss,
+            security: .allowlist,
+            allowlistMatch: entry,
+            skillAllow: false))
+        #expect(!ExecApprovalHelpers.requiresAsk(
+            ask: .onMiss,
+            security: .allowlist,
+            allowlistMatch: nil,
+            skillAllow: true))
+        #expect(!ExecApprovalHelpers.requiresAsk(
+            ask: .off,
+            security: .allowlist,
+            allowlistMatch: nil,
+            skillAllow: false))
+    }
+}

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/ClawdbotKit/GatewayChannel.swift

@@ -571,7 +571,14 @@ public actor GatewayChannelActor {
             id: id,
             method: method,
             params: paramsObject)
-        let data = try self.encoder.encode(frame)
+        let data: Data
+        do {
+            data = try self.encoder.encode(frame)
+        } catch {
+            self.logger.error(
+                "gateway request encode failed \(method, privacy: .public) error=\(error.localizedDescription, privacy: .public)")
+            throw error
+        }
         let response = try await withCheckedThrowingContinuation { (cont: CheckedContinuation<GatewayFrame, Error>) in
             self.pending[id] = cont
             Task { [weak self] in

apps/shared/ClawdbotKit/Sources/ClawdbotKit/GatewayNodeSession.swift

@@ -219,8 +219,8 @@ public actor GatewayNodeSession {
         }
         if let error = response.error {
             params["error"] = AnyCodable([
-                "code": AnyCodable(error.code.rawValue),
-                "message": AnyCodable(error.message),
+                "code": error.code.rawValue,
+                "message": error.message,
             ])
         }
         do {

apps/shared/ClawdbotKit/Sources/ClawdbotKit/SystemCommands.swift

@@ -30,6 +30,7 @@ public struct ClawdbotSystemRunParams: Codable, Sendable, Equatable {
     public var agentId: String?
     public var sessionKey: String?
     public var approved: Bool?
+    public var approvalDecision: String?
 
     public init(
         command: [String],
@@ -40,7 +41,8 @@ public struct ClawdbotSystemRunParams: Codable, Sendable, Equatable {
         needsScreenRecording: Bool? = nil,
         agentId: String? = nil,
         sessionKey: String? = nil,
-        approved: Bool? = nil)
+        approved: Bool? = nil,
+        approvalDecision: String? = nil)
     {
         self.command = command
         self.rawCommand = rawCommand
@@ -51,6 +53,7 @@ public struct ClawdbotSystemRunParams: Codable, Sendable, Equatable {
         self.agentId = agentId
         self.sessionKey = sessionKey
         self.approved = approved
+        self.approvalDecision = approvalDecision
     }
 }
 

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

@@ -18,6 +18,7 @@ public struct ConnectParams: Codable, Sendable {
     public let caps: [String]?
     public let commands: [String]?
     public let permissions: [String: AnyCodable]?
+    public let pathenv: String?
     public let role: String?
     public let scopes: [String]?
     public let device: [String: AnyCodable]?
@@ -32,6 +33,7 @@ public struct ConnectParams: Codable, Sendable {
         caps: [String]?,
         commands: [String]?,
         permissions: [String: AnyCodable]?,
+        pathenv: String?,
         role: String?,
         scopes: [String]?,
         device: [String: AnyCodable]?,
@@ -45,6 +47,7 @@ public struct ConnectParams: Codable, Sendable {
         self.caps = caps
         self.commands = commands
         self.permissions = permissions
+        self.pathenv = pathenv
         self.role = role
         self.scopes = scopes
         self.device = device
@@ -59,6 +62,7 @@ public struct ConnectParams: Codable, Sendable {
         case caps
         case commands
         case permissions
+        case pathenv = "pathEnv"
         case role
         case scopes
         case device
@@ -1904,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?
@@ -1915,6 +1920,7 @@ public struct ExecApprovalRequestParams: Codable, Sendable {
     public let timeoutms: Int?
 
     public init(
+        id: String?,
         command: String,
         cwd: String?,
         host: String?,
@@ -1925,6 +1931,7 @@ public struct ExecApprovalRequestParams: Codable, Sendable {
         sessionkey: String?,
         timeoutms: Int?
     ) {
+        self.id = id
         self.command = command
         self.cwd = cwd
         self.host = host
@@ -1936,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/concepts/model-providers.md

@@ -38,7 +38,7 @@ Clawdbot ships with the pi‑ai catalog. These providers require **no**
 - Provider: `anthropic`
 - Auth: `ANTHROPIC_API_KEY` or `claude setup-token`
 - Example model: `anthropic/claude-opus-4-5`
-- CLI: `clawdbot onboard --auth-choice setup-token`
+- CLI: `clawdbot onboard --auth-choice token` (paste setup-token) or `clawdbot models auth paste-token --provider anthropic`
 
 ```json5
 {

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: {
@@ -2671,6 +2659,8 @@ Control UI base path:
 - `gateway.controlUi.basePath` sets the URL prefix where the Control UI is served.
 - Examples: `"/ui"`, `"/clawdbot"`, `"/apps/clawdbot"`.
 - Default: root (`/`) (unchanged).
+- `gateway.controlUi.allowInsecureAuth` allows token-only auth over **HTTP** (no device identity).
+  Default: `false`. Prefer HTTPS (Tailscale Serve) or `127.0.0.1`.
 
 Related docs:
 - [Control UI](/web/control-ui)
@@ -2682,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
@@ -2699,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.
@@ -2710,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.
@@ -2724,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.
@@ -3001,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)
@@ -3031,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/gateway/protocol.md

@@ -198,6 +198,7 @@ The Gateway treats these as **claims** and enforces server-side allowlists.
 - **Local** connects include loopback and the gateway host’s own tailnet address
   (so same‑host tailnet binds can still auto‑approve).
 - All WS clients must include `device` identity during `connect` (operator + node).
+  Control UI can omit it **only** when `gateway.controlUi.allowInsecureAuth` is enabled.
 - Non-local connections must sign the server-provided `connect.challenge` nonce.
 
 ## TLS + pinning

docs/gateway/security.md

@@ -52,6 +52,15 @@ When the audit prints findings, treat this as a priority order:
 5. **Plugins/extensions**: only load what you explicitly trust.
 6. **Model choice**: prefer modern, instruction-hardened models for any bot with tools.
 
+## Control UI over HTTP
+
+The Control UI needs a **secure context** (HTTPS or localhost) to generate device
+identity. If you enable `gateway.controlUi.allowInsecureAuth`, the UI falls back
+to **token-only auth** on plain HTTP and skips device pairing. This is a security
+downgrade—prefer HTTPS (Tailscale Serve) or open the UI on `127.0.0.1`.
+
+`clawdbot security audit` warns when this setting is enabled.
+
 ## Local session logs live on disk
 
 Clawdbot stores session transcripts on disk under `~/.clawdbot/agents/<agentId>/sessions/*.jsonl`.

docs/gateway/troubleshooting.md

@@ -31,6 +31,19 @@ See also: [Health checks](/gateway/health) and [Logging](/logging).
 
 ## Common Issues
 
+### Control UI fails on HTTP ("device identity required" / "connect failed")
+
+If you open the dashboard over plain HTTP (e.g. `http://<lan-ip>:18789/` or
+`http://<tailscale-ip>:18789/`), the browser runs in a **non-secure context** and
+blocks WebCrypto, so device identity can’t be generated.
+
+**Fix:**
+- Prefer HTTPS via [Tailscale Serve](/gateway/tailscale).
+- Or open locally on the gateway host: `http://127.0.0.1:18789/`.
+- If you must stay on HTTP, enable `gateway.controlUi.allowInsecureAuth: true` and
+  use a gateway token (token-only; no device identity/pairing). See
+  [Control UI](/web/control-ui#insecure-http).
+
 ### CI Secrets Scan Failed
 
 This means `detect-secrets` found new candidates not yet in the baseline.
@@ -69,6 +82,34 @@ Doctor/service will show runtime state (PID/last exit) and log hints.
 
 See [/logging](/logging) for a full overview of formats, config, and access.
 
+### "Gateway start blocked: set gateway.mode=local"
+
+This means the config exists but `gateway.mode` is unset (or not `local`), so the
+Gateway refuses to start.
+
+**Fix (recommended):**
+- Run the wizard and set the Gateway run mode to **Local**:
+  ```bash
+  clawdbot configure
+  ```
+- Or set it directly:
+  ```bash
+  clawdbot config set gateway.mode local
+  ```
+
+**If you meant to run a remote Gateway instead:**
+- Set a remote URL and keep `gateway.mode=remote`:
+  ```bash
+  clawdbot config set gateway.mode remote
+  clawdbot config set gateway.remote.url "wss://gateway.example.com"
+  ```
+
+**Ad-hoc/dev only:** pass `--allow-unconfigured` to start the gateway without
+`gateway.mode=local`.
+
+**No config file yet?** Run `clawdbot setup` to create a starter config, then rerun
+the gateway.
+
 ### Service Environment (PATH + runtime)
 
 The gateway service runs with a **minimal PATH** to avoid shell/manager cruft:

docs/help/troubleshooting.md

@@ -38,6 +38,11 @@ Almost always a Node/npm PATH issue. Start here:
 - [Gateway troubleshooting](/gateway/troubleshooting)
 - [Gateway authentication](/gateway/authentication)
 
+### Control UI fails on HTTP (device identity required)
+
+- [Gateway troubleshooting](/gateway/troubleshooting)
+- [Control UI](/web/control-ui#insecure-http)
+
 ### Service says running, but RPC probe fails
 
 - [Gateway troubleshooting](/gateway/troubleshooting)

docs/platforms/mac/release.md

@@ -24,22 +24,23 @@ This app now ships Sparkle auto-updates. Release builds must be Developer ID–s
 Notes:
 - `APP_BUILD` maps to `CFBundleVersion`/`sparkle:version`; keep it numeric + monotonic (no `-beta`), or Sparkle compares it as equal.
 - Defaults to the current architecture (`$(uname -m)`). For release/universal builds, set `BUILD_ARCHS="arm64 x86_64"` (or `BUILD_ARCHS=all`).
+- Use `scripts/package-mac-dist.sh` for release artifacts (zip + DMG + notarization). Use `scripts/package-mac-app.sh` for local/dev packaging.
 
 ```bash
 # 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:
@@ -47,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/providers/anthropic.md

@@ -70,11 +70,9 @@ Setup-tokens are created by the **Claude Code CLI**, not the Anthropic Console.
 claude setup-token
 ```
 
-Paste the token into Clawdbot (wizard: **Anthropic token (paste setup-token)**), or let Clawdbot run the command locally:
+Paste the token into Clawdbot (wizard: **Anthropic token (paste setup-token)**), or run it on the gateway host:
 
 ```bash
-clawdbot onboard --auth-choice setup-token
-# or
 clawdbot models auth setup-token --provider anthropic
 ```
 
@@ -87,9 +85,6 @@ clawdbot models auth paste-token --provider anthropic
 ### CLI setup
 
 ```bash
-# Run setup-token locally (wizard can run it for you)
-clawdbot onboard --auth-choice setup-token
-
 # Reuse Claude Code CLI OAuth credentials if already logged in
 clawdbot onboard --auth-choice claude-cli
 ```
@@ -104,7 +99,7 @@ clawdbot onboard --auth-choice claude-cli
 
 ## Notes
 
-- The wizard can run `claude setup-token` locally and store the token, or you can paste a token generated elsewhere.
+- Generate the setup-token with `claude setup-token` and paste it, or run `clawdbot models auth setup-token` on the gateway host.
 - Clawdbot writes `auth.profiles["anthropic:claude-cli"].mode` as `"oauth"` so the profile
   accepts both OAuth and setup-token credentials. Older configs using `"token"` are
   auto-migrated on load.

docs/start/faq.md

@@ -241,7 +241,7 @@ It also warns if your configured model is unknown or missing auth.
 
 ### How does Anthropic "setup-token" auth work?
 
-`claude setup-token` generates a **token string** via the Claude Code CLI (it is not available in the web console). You can run it on **any machine**. If you run it on the gateway host, the wizard can auto-detect the CLI credentials. If you run it elsewhere, choose **Anthropic token (paste setup-token)** and paste the string. The token is stored as an auth profile for the **anthropic** provider and used like an API key or OAuth profile. More detail: [OAuth](/concepts/oauth).
+`claude setup-token` generates a **token string** via the Claude Code CLI (it is not available in the web console). You can run it on **any machine**. If Claude Code CLI credentials are present on the gateway host, Clawdbot can reuse them; otherwise choose **Anthropic token (paste setup-token)** and paste the string. The token is stored as an auth profile for the **anthropic** provider and used like an API key or OAuth profile. More detail: [OAuth](/concepts/oauth).
 
 Clawdbot keeps `auth.profiles["anthropic:claude-cli"].mode` set to `"oauth"` so
 the profile accepts both OAuth and setup-token credentials; older `"token"` mode
@@ -255,11 +255,11 @@ It is **not** in the Anthropic Console. The setup-token is generated by the **Cl
 claude setup-token
 ```
 
-Copy the token it prints, then choose **Anthropic token (paste setup-token)** in the wizard. If you want Clawdbot to run the command for you, use `clawdbot onboard --auth-choice setup-token` or `clawdbot models auth setup-token --provider anthropic`. If you ran `claude setup-token` elsewhere, paste it on the gateway host with `clawdbot models auth paste-token --provider anthropic`. See [Anthropic](/providers/anthropic).
+Copy the token it prints, then choose **Anthropic token (paste setup-token)** in the wizard. If you want to run it on the gateway host, use `clawdbot models auth setup-token --provider anthropic`. If you ran `claude setup-token` elsewhere, paste it on the gateway host with `clawdbot models auth paste-token --provider anthropic`. See [Anthropic](/providers/anthropic).
 
 ### Do you support Claude subscription auth (Claude Code OAuth)?
 
-Yes. Clawdbot can **reuse Claude Code CLI credentials** (OAuth) and also supports **setup-token**. If you have a Claude subscription, we recommend **setup-token** for long‑running setups (requires Claude Pro/Max + the `claude` CLI). You can generate it anywhere and paste it on the gateway host, or run it locally on the gateway so it auto-syncs. OAuth reuse is supported, but avoid logging in separately via Clawdbot and Claude Code to prevent token conflicts. See [Anthropic](/providers/anthropic) and [OAuth](/concepts/oauth).
+Yes. Clawdbot can **reuse Claude Code CLI credentials** (OAuth) and also supports **setup-token**. If you have a Claude subscription, we recommend **setup-token** for long‑running setups (requires Claude Pro/Max + the `claude` CLI). You can generate it anywhere and paste it on the gateway host. OAuth reuse is supported, but avoid logging in separately via Clawdbot and Claude Code to prevent token conflicts. See [Anthropic](/providers/anthropic) and [OAuth](/concepts/oauth).
 
 Note: Claude subscription access is governed by Anthropic’s terms. For production or multi‑user workloads, API keys are usually the safer choice.
 

docs/start/wizard.md

@@ -45,7 +45,7 @@ The wizard starts with **QuickStart** (defaults) vs **Advanced** (full control).
 ## What the wizard does
 
 **Local mode (default)** walks you through:
-  - Model/auth (OpenAI Code (Codex) subscription OAuth, Anthropic API key (recommended) or `claude setup-token`, plus MiniMax/GLM/Moonshot/AI Gateway options)
+  - Model/auth (OpenAI Code (Codex) subscription OAuth, Anthropic API key (recommended) or setup-token (paste), plus MiniMax/GLM/Moonshot/AI Gateway options)
 - Workspace location + bootstrap files
 - Gateway settings (port/bind/auth/tailscale)
 - Providers (Telegram, WhatsApp, Discord, Signal)
@@ -79,9 +79,8 @@ Tip: `--json` does **not** imply non-interactive mode. Use `--non-interactive` (
 
 2) **Model/Auth**
    - **Anthropic API key (recommended)**: uses `ANTHROPIC_API_KEY` if present or prompts for a key, then saves it for daemon use.
-   - **Anthropic token (setup-token)**: run `claude setup-token` locally (the wizard can run it for you and reuse the token) or run it elsewhere and paste the token.
    - **Anthropic OAuth (Claude Code CLI)**: on macOS the wizard checks Keychain item "Claude Code-credentials" (choose "Always Allow" so launchd starts don't block); on Linux/Windows it reuses `~/.claude/.credentials.json` if present.
-   - **Anthropic token (paste setup-token)**: run `claude setup-token` in your terminal, then paste the token (you can name it; blank = default).
+   - **Anthropic token (paste setup-token)**: run `claude setup-token` on any machine, then paste the token (you can name it; blank = default).
    - **OpenAI Code (Codex) subscription (Codex CLI)**: if `~/.codex/auth.json` exists, the wizard can reuse it.
    - **OpenAI Code (Codex) subscription (OAuth)**: browser flow; paste the `code#state`.
      - Sets `agents.defaults.model` to `openai-codex/gpt-5.2` when model is unset or `openai/*`.

docs/tools/exec-approvals.md

@@ -87,6 +87,7 @@ If a prompt is required but no UI is reachable, fallback decides:
 
 Allowlists are **per agent**. If multiple agents exist, switch which agent you’re
 editing in the macOS app. Patterns are **case-insensitive glob matches**.
+Patterns should resolve to **binary paths** (basename-only entries are ignored).
 
 Examples:
 - `~/Projects/**/bin/bird`
@@ -104,6 +105,15 @@ When **Auto-allow skill CLIs** is enabled, executables referenced by known skill
 are treated as allowlisted on nodes (macOS node or headless node host). This uses the Bridge RPC to ask the
 gateway for the skill bin list. Disable this if you want strict manual allowlists.
 
+## Safe bins (stdin-only)
+
+`tools.exec.safeBins` defines a small list of **stdin-only** binaries (for example `jq`)
+that can run in allowlist mode **without** explicit allowlist entries. Safe bins reject
+positional file args and path-like tokens, so they can only operate on the incoming stream.
+Shell chaining and redirections are not auto-allowed in allowlist mode.
+
+Default safe bins: `jq`, `grep`, `cut`, `sort`, `uniq`, `head`, `tail`, `tr`, `wc`.
+
 ## Control UI editing
 
 Use the **Control UI → Nodes → Exec approvals** card to edit defaults, per‑agent
@@ -124,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
@@ -152,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,11 +38,13 @@ 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`)
 - `tools.exec.node` (default: unset)
 - `tools.exec.pathPrepend`: list of directories to prepend to `PATH` for exec runs.
+- `tools.exec.safeBins`: stdin-only safe binaries that can run without explicit allowlist entries.
 
 Example:
 ```json5
@@ -64,7 +66,8 @@ Example:
 - `host=sandbox`: runs `sh -lc` (login shell) inside the container, so `/etc/profile` may reset `PATH`.
   Clawdbot prepends `env.PATH` after profile sourcing; `tools.exec.pathPrepend` applies here too.
 - `host=node`: only env overrides you pass are sent to the node. `tools.exec.pathPrepend` only applies
-  if the exec call already sets `env.PATH`.
+  if the exec call already sets `env.PATH`. Node PATH overrides are accepted only when they prepend
+  the node host PATH (no replacement).
 
 Per-agent node binding (use the agent list index in config):
 
@@ -90,6 +93,18 @@ 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
+`security=allowlist`, shell commands are auto-allowed only if every pipeline segment is
+allowlisted or a safe bin. Chaining (`;`, `&&`, `||`) and redirections are rejected in
+allowlist mode.
+
 ## Examples
 
 Foreground:

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"
+→ clawd calls gmail.list
+→ LLM summarizes
+→ User: "draft replies to #2 and #5"
+→ LLM drafts
+→ User: "send #2"
+→ clawd calls gmail.send
+(repeat daily, no memory of what was triaged)
+```
+
+With Lobster:
+```
+clawd 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 → clawd 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.

docs/web/control-ui.md

@@ -86,6 +86,33 @@ Then open:
 
 Paste the token into the UI settings (sent as `connect.params.auth.token`).
 
+## Insecure HTTP
+
+If you open the dashboard over plain HTTP (`http://<lan-ip>` or `http://<tailscale-ip>`),
+the browser runs in a **non-secure context** and blocks WebCrypto. By default,
+Clawdbot **blocks** Control UI connections without device identity.
+
+**Recommended fix:** use HTTPS (Tailscale Serve) or open the UI locally:
+- `https://<magicdns>/` (Serve)
+- `http://127.0.0.1:18789/` (on the gateway host)
+
+**Downgrade example (token-only over HTTP):**
+
+```json5
+{
+  gateway: {
+    controlUi: { allowInsecureAuth: true },
+    bind: "tailnet",
+    auth: { mode: "token", token: "replace-me" }
+  }
+}
+```
+
+This disables device identity + pairing for the Control UI. Use only if you
+trust the network.
+
+See [Tailscale](/gateway/tailscale) for HTTPS setup guidance.
+
 ## Building the UI
 
 The Gateway serves static files from `dist/control-ui`. Build them with:

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/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,112 @@
+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;
+}) {
+  const dir = await fs.mkdtemp(path.join(os.tmpdir(), "clawdbot-lobster-plugin-"));
+  const binPath = path.join(dir, "lobster");
+
+  const file = `#!/usr/bin/env node\n` +
+    `process.stdout.write(JSON.stringify(${JSON.stringify(params.payload)}));\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("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,185 @@
+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;
+}) {
+  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) => {
+    const child = spawn(execPath, argv, {
+      cwd,
+      stdio: ["ignore", "pipe", "pipe"],
+      env: {
+        ...process.env,
+        LOBSTER_MODE: "tool",
+      },
+    });
+
+    let stdout = "";
+    let stdoutBytes = 0;
+    let stderr = "";
+
+    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 {
+          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 {
+        reject(new Error("lobster subprocess timed out"));
+      }
+    }, timeoutMs);
+
+    child.once("error", (err) => {
+      clearTimeout(timer);
+      reject(err);
+    });
+
+    child.once("exit", (code) => {
+      clearTimeout(timer);
+      if (code !== 0) {
+        reject(new Error(`lobster failed (${code ?? "?"}): ${stderr.trim() || stdout.trim()}`));
+        return;
+      }
+      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>) {
+      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,
+      });
+
+      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": {

extensions/zalouser/src/zca.ts

@@ -114,11 +114,36 @@ export function runZcaInteractive(
   });
 }
 
+function stripAnsi(str: string): string {
+  return str.replace(/\x1B\[[0-9;]*[a-zA-Z]/g, "");
+}
+
 export function parseJsonOutput<T>(stdout: string): T | null {
   try {
     return JSON.parse(stdout) as T;
   } catch {
-    return null;
+    const cleaned = stripAnsi(stdout);
+
+    try {
+      return JSON.parse(cleaned) as T;
+    } catch {
+      // zca may prefix output with INFO/log lines, try to find JSON
+      const lines = cleaned.split("\n");
+
+      for (let i = 0; i < lines.length; i++) {
+        const line = lines[i].trim();
+        if (line.startsWith("{") || line.startsWith("[")) {
+          // Try parsing from this line to the end
+          const jsonCandidate = lines.slice(i).join("\n").trim();
+          try {
+            return JSON.parse(jsonCandidate) as T;
+          } catch {
+            continue;
+          }
+        }
+      }
+      return null;
+    }
   }
 }
 

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",

scripts/package-mac-app.sh

@@ -227,15 +227,29 @@ fi
 
 echo "📦 Copying Textual resources"
 TEXTUAL_BUNDLE_DIR="$(build_path_for_arch "$PRIMARY_ARCH")/$BUILD_CONFIG"
-TEXTUAL_BUNDLE="$TEXTUAL_BUNDLE_DIR/textual_Textual.bundle"
-if [ ! -d "$TEXTUAL_BUNDLE" ]; then
-  TEXTUAL_BUNDLE="$TEXTUAL_BUNDLE_DIR/Textual_Textual.bundle"
+TEXTUAL_BUNDLE=""
+for candidate in \
+  "$TEXTUAL_BUNDLE_DIR/textual_Textual.bundle" \
+  "$TEXTUAL_BUNDLE_DIR/Textual_Textual.bundle"
+do
+  if [ -d "$candidate" ]; then
+    TEXTUAL_BUNDLE="$candidate"
+    break
+  fi
+done
+if [ -z "$TEXTUAL_BUNDLE" ]; then
+  TEXTUAL_BUNDLE="$(find "$BUILD_ROOT" -type d \( -name "textual_Textual.bundle" -o -name "Textual_Textual.bundle" \) -print -quit)"
 fi
-if [ -d "$TEXTUAL_BUNDLE" ]; then
+if [ -n "$TEXTUAL_BUNDLE" ] && [ -d "$TEXTUAL_BUNDLE" ]; then
   rm -rf "$APP_ROOT/Contents/Resources/$(basename "$TEXTUAL_BUNDLE")"
   cp -R "$TEXTUAL_BUNDLE" "$APP_ROOT/Contents/Resources/"
 else
-  echo "WARN: Textual resource bundle not found in $TEXTUAL_BUNDLE_DIR (continuing)" >&2
+  if [[ "${ALLOW_MISSING_TEXTUAL_BUNDLE:-0}" == "1" ]]; then
+    echo "WARN: Textual resource bundle not found (continuing due to ALLOW_MISSING_TEXTUAL_BUNDLE=1)" >&2
+  else
+    echo "ERROR: Textual resource bundle not found. Set ALLOW_MISSING_TEXTUAL_BUNDLE=1 to bypass." >&2
+    exit 1
+  fi
 fi
 
 echo "⏹  Stopping any running Clawdbot"

scripts/package-mac-dist.sh

@@ -10,6 +10,9 @@ set -euo pipefail
 
 ROOT_DIR="$(cd "$(dirname "$0")/.." && pwd)"
 
+# Default to universal binary for distribution builds (supports both Apple Silicon and Intel Macs)
+export BUILD_ARCHS="${BUILD_ARCHS:-all}"
+
 "$ROOT_DIR/scripts/package-mac-app.sh"
 
 APP="$ROOT_DIR/dist/Clawdbot.app"

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/model.test.ts

@@ -10,10 +10,11 @@ describe("extractModelDirective", () => {
       expect(result.cleaned).toBe("");
     });
 
-    it("does not extract /models with argument", () => {
+    it("extracts /models with argument", () => {
       const result = extractModelDirective("/models gpt-5");
-      expect(result.hasDirective).toBe(false);
-      expect(result.cleaned).toBe("/models gpt-5");
+      expect(result.hasDirective).toBe(true);
+      expect(result.rawModel).toBe("gpt-5");
+      expect(result.cleaned).toBe("");
     });
 
     it("extracts /model with provider/model format", () => {
@@ -113,10 +114,9 @@ describe("extractModelDirective", () => {
   });
 
   describe("edge cases", () => {
-    it("extracts models with multiple path segments", () => {
+    it("absorbs path-like segments when /model includes extra slashes", () => {
       const result = extractModelDirective("thats not /model gpt-5/tmp/hello");
       expect(result.hasDirective).toBe(true);
-      expect(result.rawModel).toBe("gpt-5/tmp/hello");
       expect(result.cleaned).toBe("thats not");
     });
 

src/auto-reply/model.ts

@@ -14,7 +14,7 @@ export function extractModelDirective(
   if (!body) return { cleaned: "", hasDirective: false };
 
   const modelMatch = body.match(
-    /(?:^|\s)\/model(?=$|\s|:)\s*:?\s*([A-Za-z0-9_.:@-]+(?:\/[A-Za-z0-9_.:@-]+)*)?/i,
+    /(?:^|\s)\/models?(?=$|\s|:)\s*:?\s*([A-Za-z0-9_.:@-]+(?:\/[A-Za-z0-9_.:@-]+)*)?/i,
   );
 
   const aliases = (options?.aliases ?? []).map((alias) => alias.trim()).filter(Boolean);

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

@@ -60,13 +60,13 @@ describe("directive behavior", () => {
     vi.restoreAllMocks();
   });
 
-  it("lists allowlisted models on /models <provider>", async () => {
+  it("aliases /model list to /models", async () => {
     await withTempHome(async (home) => {
       vi.mocked(runEmbeddedPiAgent).mockReset();
       const storePath = path.join(home, "sessions.json");
 
       const res = await getReplyFromConfig(
-        { Body: "/models anthropic", From: "+1222", To: "+1222", CommandAuthorized: true },
+        { Body: "/model list", From: "+1222", To: "+1222", CommandAuthorized: true },
         {},
         {
           agents: {
@@ -84,40 +84,22 @@ describe("directive behavior", () => {
       );
 
       const text = Array.isArray(res) ? res[0]?.text : res?.text;
-      expect(text).toContain("Models (anthropic)");
-      expect(text).toContain("anthropic/claude-opus-4-5");
-
-      const openaiRes = await getReplyFromConfig(
-        { Body: "/models openai", From: "+1222", To: "+1222", CommandAuthorized: true },
-        {},
-        {
-          agents: {
-            defaults: {
-              model: { primary: "anthropic/claude-opus-4-5" },
-              workspace: path.join(home, "clawd"),
-              models: {
-                "anthropic/claude-opus-4-5": {},
-                "openai/gpt-4.1-mini": {},
-              },
-            },
-          },
-          session: { store: storePath },
-        },
-      );
-      const openaiText = Array.isArray(openaiRes) ? openaiRes[0]?.text : openaiRes?.text;
-      expect(openaiText).toContain("Models (openai)");
-      expect(openaiText).toContain("openai/gpt-4.1-mini");
+      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([]);
       const storePath = path.join(home, "sessions.json");
 
       const res = await getReplyFromConfig(
-        { Body: "/models anthropic", From: "+1222", To: "+1222", CommandAuthorized: true },
+        { Body: "/model", From: "+1222", To: "+1222", CommandAuthorized: true },
         {},
         {
           agents: {
@@ -135,36 +117,17 @@ describe("directive behavior", () => {
       );
 
       const text = Array.isArray(res) ? res[0]?.text : res?.text;
-      expect(text).toContain("Models (anthropic)");
-      expect(text).toContain("anthropic/claude-opus-4-5");
-
-      const openaiRes = await getReplyFromConfig(
-        { Body: "/models openai", From: "+1222", To: "+1222", CommandAuthorized: true },
-        {},
-        {
-          agents: {
-            defaults: {
-              model: { primary: "anthropic/claude-opus-4-5" },
-              workspace: path.join(home, "clawd"),
-              models: {
-                "anthropic/claude-opus-4-5": {},
-                "openai/gpt-4.1-mini": {},
-              },
-            },
-          },
-          session: { store: storePath },
-        },
-      );
-      const openaiText = Array.isArray(openaiRes) ? openaiRes[0]?.text : openaiRes?.text;
-      expect(openaiText).toContain("Models (openai)");
-      expect(openaiText).toContain("openai/gpt-4.1-mini");
+      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" },
@@ -172,7 +135,7 @@ describe("directive behavior", () => {
       const storePath = path.join(home, "sessions.json");
 
       const res = await getReplyFromConfig(
-        { Body: "/models xai", From: "+1222", To: "+1222", CommandAuthorized: true },
+        { Body: "/model list", From: "+1222", To: "+1222", CommandAuthorized: true },
         {},
         {
           agents: {
@@ -190,33 +153,15 @@ describe("directive behavior", () => {
       );
 
       const text = Array.isArray(res) ? res[0]?.text : res?.text;
-      expect(text).toContain("Models (xai)");
-      expect(text).toContain("xai/grok-4");
-
-      const minimaxRes = await getReplyFromConfig(
-        { Body: "/models minimax", From: "+1222", To: "+1222", CommandAuthorized: true },
-        {},
-        {
-          agents: {
-            defaults: {
-              model: {
-                primary: "anthropic/claude-opus-4-5",
-                fallbacks: ["openai/gpt-4.1-mini"],
-              },
-              imageModel: { primary: "minimax/MiniMax-M2.1" },
-              workspace: path.join(home, "clawd"),
-            },
-          },
-          session: { store: storePath },
-        },
-      );
-      const minimaxText = Array.isArray(minimaxRes) ? minimaxRes[0]?.text : minimaxRes?.text;
-      expect(minimaxText).toContain("Models (minimax)");
-      expect(minimaxText).toContain("minimax/MiniMax-M2.1");
+      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
@@ -261,7 +206,7 @@ describe("directive behavior", () => {
       );
 
       const text = Array.isArray(res) ? res[0]?.text : res?.text;
-      expect(text).toContain("Models (minimax)");
+      expect(text).toContain("Model set to minimax");
       expect(text).toContain("minimax/MiniMax-M2.1");
       expect(runEmbeddedPiAgent).not.toHaveBeenCalled();
     });
@@ -289,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

@@ -62,13 +62,13 @@ describe("directive behavior", () => {
     vi.restoreAllMocks();
   });
 
-  it("selects exact alias matches even when ambiguous", async () => {
+  it("prefers alias matches when fuzzy selection is ambiguous", async () => {
     await withTempHome(async (home) => {
       vi.mocked(runEmbeddedPiAgent).mockReset();
       const storePath = path.join(home, "sessions.json");
 
-      await getReplyFromConfig(
-        { Body: "/model Kimi", From: "+1222", To: "+1222", CommandAuthorized: true },
+      const res = await getReplyFromConfig(
+        { Body: "/model ki", From: "+1222", To: "+1222", CommandAuthorized: true },
         {},
         {
           agents: {
@@ -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

@@ -95,9 +95,11 @@ describe("directive behavior", () => {
       );
 
       const text = Array.isArray(res) ? res[0]?.text : res?.text;
-      expect(text).toContain("Did you mean:");
-      expect(text).toContain("moonshot/kimi-k2-0905-preview");
-      assertModelSelection(storePath);
+      expect(text).toContain("Model set to moonshot/kimi-k2-0905-preview.");
+      assertModelSelection(storePath, {
+        provider: "moonshot",
+        model: "kimi-k2-0905-preview",
+      });
       expect(runEmbeddedPiAgent).not.toHaveBeenCalled();
     });
   });
@@ -141,9 +143,11 @@ describe("directive behavior", () => {
       );
 
       const text = Array.isArray(res) ? res[0]?.text : res?.text;
-      expect(text).toContain("Did you mean:");
-      expect(text).toContain("moonshot/kimi-k2-0905-preview");
-      assertModelSelection(storePath);
+      expect(text).toContain("Model set to moonshot/kimi-k2-0905-preview.");
+      assertModelSelection(storePath, {
+        provider: "moonshot",
+        model: "kimi-k2-0905-preview",
+      });
       expect(runEmbeddedPiAgent).not.toHaveBeenCalled();
     });
   });
@@ -182,9 +186,11 @@ describe("directive behavior", () => {
       );
 
       const text = Array.isArray(res) ? res[0]?.text : res?.text;
-      expect(text).toContain("Did you mean:");
-      expect(text).toContain("moonshot/kimi-k2-0905-preview");
-      assertModelSelection(storePath);
+      expect(text).toContain("Model set to moonshot/kimi-k2-0905-preview.");
+      assertModelSelection(storePath, {
+        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("shows a model summary 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("Browse: /models");
       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

@@ -95,7 +95,7 @@ afterEach(() => {
 });
 
 describe("trigger handling", () => {
-  it("shows a /model summary with browse hints", async () => {
+  it("shows a /model summary and points to /models", async () => {
     await withTempHome(async (home) => {
       const cfg = makeCfg(home);
       const res = await getReplyFromConfig(
@@ -116,17 +116,19 @@ describe("trigger handling", () => {
       const text = Array.isArray(res) ? res[0]?.text : res?.text;
       const normalized = normalizeTestText(text ?? "");
       expect(normalized).toContain("Current: anthropic/claude-opus-4-5");
-      expect(normalized).toContain("Browse: /models");
       expect(normalized).toContain("Switch: /model <provider/model>");
+      expect(normalized).toContain("Browse: /models (providers) or /models <provider> (models)");
       expect(normalized).toContain("More: /model status");
+      expect(normalized).not.toContain("reasoning");
+      expect(normalized).not.toContain("image");
     });
   });
-  it("lists providers on /models", async () => {
+  it("aliases /model list to /models", async () => {
     await withTempHome(async (home) => {
       const cfg = makeCfg(home);
       const res = await getReplyFromConfig(
         {
-          Body: "/models",
+          Body: "/model list",
           From: "telegram:111",
           To: "telegram:111",
           ChatType: "direct",
@@ -142,11 +144,8 @@ describe("trigger handling", () => {
       const text = Array.isArray(res) ? res[0]?.text : res?.text;
       const normalized = normalizeTestText(text ?? "");
       expect(normalized).toContain("Providers:");
-      expect(normalized).toContain("anthropic");
-      expect(normalized).toContain("openrouter");
-      expect(normalized).toContain("openai");
-      expect(normalized).toContain("openai-codex");
-      expect(normalized).toContain("minimax");
+      expect(normalized).toContain("Use: /models <provider>");
+      expect(normalized).toContain("Switch: /model <provider/model>");
     });
   });
   it("selects the exact provider/model pair for openrouter", async () => {
@@ -200,16 +199,17 @@ describe("trigger handling", () => {
       );
 
       const text = Array.isArray(res) ? res[0]?.text : res?.text;
-      expect(normalizeTestText(text ?? "")).toContain(
-        "Numeric model selection is not supported in chat.",
-      );
+      const normalized = normalizeTestText(text ?? "");
+      expect(normalized).toContain("Numeric model selection is not supported in chat.");
+      expect(normalized).toContain("Browse: /models or /models <provider>");
+      expect(normalized).toContain("Switch: /model <provider/model>");
 
       const store = loadSessionStore(cfg.session.store);
       expect(store[sessionKey]?.providerOverride).toBeUndefined();
       expect(store[sessionKey]?.modelOverride).toBeUndefined();
     });
   });
-  it("selects exact provider/model combo via /model <provider/model>", async () => {
+  it("resets to the default model via /model <provider/model>", async () => {
     await withTempHome(async (home) => {
       const cfg = makeCfg(home);
       const sessionKey = "telegram:slash:111";
@@ -231,7 +231,7 @@ describe("trigger handling", () => {
 
       const text = Array.isArray(res) ? res[0]?.text : res?.text;
       expect(normalizeTestText(text ?? "")).toContain(
-        "Model reset to default (anthropic/claude-opus-4-5).",
+        "Model reset to default (anthropic/claude-opus-4-5)",
       );
 
       const store = loadSessionStore(cfg.session.store);

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

@@ -80,47 +80,14 @@ describe("/models command", () => {
     expect(result.reply?.text).toContain("All: /models anthropic all");
   });
 
-  it("includes configured providers and defaults", async () => {
-    const configuredCfg = {
-      commands: { text: true },
-      agents: {
-        defaults: {
-          model: {
-            primary: "synthetic/synth-1",
-            fallbacks: ["synthetic/synth-2"],
-          },
-          imageModel: {
-            primary: "synthetic/synth-image",
-            fallbacks: ["synthetic/synth-image-2"],
-          },
-        },
-      },
-      models: {
-        providers: {
-          synthetic: {
-            baseUrl: "https://example.com",
-            models: [
-              {
-                id: "synth-3",
-                name: "Synth 3",
-              },
-            ],
-          },
-        },
-      },
-    } as unknown as ClawdbotConfig;
-
-    const providersResult = await handleCommands(buildParams("/models", configuredCfg));
-    expect(providersResult.shouldContinue).toBe(false);
-    expect(providersResult.reply?.text).toContain("synthetic");
-
-    const modelsResult = await handleCommands(buildParams("/models synthetic", configuredCfg));
-    expect(modelsResult.shouldContinue).toBe(false);
-    expect(modelsResult.reply?.text).toContain("synthetic/synth-1");
-    expect(modelsResult.reply?.text).toContain("synthetic/synth-2");
-    expect(modelsResult.reply?.text).toContain("synthetic/synth-3");
-    expect(modelsResult.reply?.text).toContain("synthetic/synth-image");
-    expect(modelsResult.reply?.text).toContain("synthetic/synth-image-2");
+  it("ignores page argument when all flag is present", async () => {
+    const params = buildParams("/models anthropic 3 all", cfg);
+    const result = await handleCommands(params);
+    expect(result.shouldContinue).toBe(false);
+    expect(result.reply?.text).toContain("Models (anthropic)");
+    expect(result.reply?.text).toContain("page 1/1");
+    expect(result.reply?.text).toContain("anthropic/claude-opus-4-5");
+    expect(result.reply?.text).not.toContain("Page out of range");
   });
 
   it("errors on out-of-range pages", async () => {
@@ -138,4 +105,29 @@ describe("/models command", () => {
     expect(result.reply?.text).toContain("Unknown provider");
     expect(result.reply?.text).toContain("Available providers");
   });
+
+  it("lists configured models outside the curated catalog", async () => {
+    const customCfg = {
+      commands: { text: true },
+      agents: {
+        defaults: {
+          model: {
+            primary: "localai/ultra-chat",
+            fallbacks: ["anthropic/claude-opus-4-5"],
+          },
+          imageModel: "visionpro/studio-v1",
+        },
+      },
+    } as unknown as ClawdbotConfig;
+
+    const providerList = await handleCommands(buildParams("/models", customCfg));
+    expect(providerList.reply?.text).toContain("localai");
+    expect(providerList.reply?.text).toContain("visionpro");
+
+    const result = await handleCommands(buildParams("/models localai", customCfg));
+    expect(result.shouldContinue).toBe(false);
+    expect(result.reply?.text).toContain("Models (localai)");
+    expect(result.reply?.text).toContain("localai/ultra-chat");
+    expect(result.reply?.text).not.toContain("Unknown provider");
+  });
 });