Re-supply user-declared external agent launchers on resume

CLI/CMUXCLI+AgentHookRestoreEvidence.swift

@@ -74,12 +74,36 @@ extension CMUXCLI {
         }
     }
 
+    /// The launch record a hook should publish for resume, with the session's external launcher
+    /// preserved.
+    ///
+    /// Selection has several early exits (a rejected capture, the codex permission-evidence branch),
+    /// and the external launcher is a property of the session rather than of whichever record wins,
+    /// so preservation wraps the whole selection instead of sitting on one path. Ancestor detection
+    /// can miss on a later hook once the launcher process is gone; a record that lost the id must
+    /// never erase it. #10494
     func preferredAgentHookResumeLaunchCommand(
         kind: String,
         current: AgentHookLaunchCommandRecord?,
         mapped: ClaudeHookSessionRecord?,
         transcriptPath: String? = nil,
         currentPID: Int? = nil
+    ) -> AgentHookLaunchCommandRecord? {
+        selectedAgentHookResumeLaunchCommand(
+            kind: kind,
+            current: current,
+            mapped: mapped,
+            transcriptPath: transcriptPath,
+            currentPID: currentPID
+        )?.preservingExternalLauncher(from: [current, mapped?.launchCommand])
+    }
+
+    private func selectedAgentHookResumeLaunchCommand(
+        kind: String,
+        current: AgentHookLaunchCommandRecord?,
+        mapped: ClaudeHookSessionRecord?,
+        transcriptPath: String?,
+        currentPID: Int?
     ) -> AgentHookLaunchCommandRecord? {
         if normalizedHookValue(current?.source)?.lowercased() == "rejected" {
             return current
@@ -126,6 +150,8 @@ extension CMUXCLI {
         )
     }
 
+
+
     func preferredAgentHookResumeWorkingDirectory(
         kind: String,
         current: AgentHookLaunchCommandRecord?,

CLI/CMUXCLI+Restore.swift

@@ -17,6 +17,9 @@ extension CMUXCLI {
         if let launcher = command.launcher {
             payload["launcher"] = launcher
         }
+        if let externalLauncher = command.externalLauncher {
+            payload["external_launcher"] = externalLauncher
+        }
         if let executablePath = command.executablePath {
             payload["executable_path"] = executablePath
         }
@@ -163,7 +166,10 @@ extension CMUXCLI {
             observedPermissionMode: record.permissionMode
         )
         guard let invocation = AgentRestorePlanner(
-            executableFileResolver: AgentRestoreExecutableFileResolver()
+            executableFileResolver: AgentRestoreExecutableFileResolver(),
+            externalLaunchers: externalAgentLaunchers(
+                workingDirectory: effectiveWorkingDirectory ?? record.launchCommand?.workingDirectory
+            )
         ).invocation(
             for: request,
             ambientEnvironment: processEnvironment
@@ -500,6 +506,7 @@ extension CMUXCLI {
         }
         return AgentLaunchCommand(
             launcher: object["launcher"] as? String,
+            externalLauncher: object["external_launcher"] as? String,
             executablePath: object["executable_path"] as? String,
             arguments: arguments,
             workingDirectory: object["working_directory"] as? String,

CLI/cmux.swift

@@ -1227,15 +1227,29 @@ final class ClaudeHookSessionStore {
             // captured) only when we don't already hold an argv-bearing one — so the durable store
             // keeps the non-default home for the fork/resume path without ever downgrading a richer
             // earlier capture to an env-only stub.
+            // Every write path into this store lands here, so the external launcher is carried
+            // across in one place: ancestor detection can miss on a later hook once the launcher
+            // process has exited, and such a record must not overwrite the wrapper id the session
+            // was captured with. #10494
             if incomingHasArguments || normalizeOptional(launchCommand.source)?.lowercased() == "rejected" || (normalizeOptional(launchCommand.source)?.lowercased() == "default" && !existingHasArguments && normalizeOptional(record.launchCommand?.environment?["CODEX_HOME"]) == nil) || (incomingHasEnvironment && !existingHasArguments) {
-                record.launchCommand = launchCommand
+                record.launchCommand = launchCommand.preservingExternalLauncher(
+                    from: [record.launchCommand]
+                )
             } else if let verificationHome = normalizeOptional(launchCommand.verificationHome),
                       var existingLaunchCommand = record.launchCommand,
                       normalizeOptional(existingLaunchCommand.verificationHome) == nil {
                 // Keep a richer argv capture while filling in the separate
                 // Codex verification hint learned by a later hook event.
                 existingLaunchCommand.verificationHome = verificationHome
-                record.launchCommand = existingLaunchCommand
+                record.launchCommand = existingLaunchCommand.preservingExternalLauncher(
+                    from: [launchCommand]
+                )
+            } else if let existingLaunchCommand = record.launchCommand {
+                // The incoming record is not rich enough to replace the stored one, but it may be
+                // the only capture that saw the launcher.
+                record.launchCommand = existingLaunchCommand.preservingExternalLauncher(
+                    from: [launchCommand]
+                )
             }
         }
         if let isRestorable {
@@ -28910,6 +28924,20 @@ struct CMUXCLI {
         return arguments.isEmpty ? nil : arguments
     }
 
+    /// User-declared launchers that wrap a built-in agent (`agents.launchers` in `cmux.json`).
+    ///
+    /// The project directory is passed in rather than taken from this process: the project-level
+    /// config that applies belongs to the agent's session, and a hook or restore process can be
+    /// started from anywhere. Read per call, like the vault agent registry — a hook invocation is
+    /// short-lived, and one config read keeps a mid-session config edit from going stale.
+    func externalAgentLaunchers(workingDirectory: String?) -> AgentExternalLauncherRegistry {
+        AgentExternalLauncherRegistry.load(
+            homeDirectory: NSHomeDirectory(),
+            workingDirectory: workingDirectory,
+            sanitize: { try JSONCParser.preprocess(data: $0) }
+        )
+    }
+
     private func agentLaunchCommandFromEnvironment(
         _ env: [String: String],
         fallbackPID: Int?,
@@ -28959,6 +28987,42 @@ struct CMUXCLI {
             ? normalizedHookValue(env["HOME"])
             : nil
 
+        // A launcher cmux does not own (a multi-account router such as teamclaude, a gateway shim)
+        // execs the agent as a child, so nothing above records it and restore would replay a bare
+        // `claude --resume <id>` outside the wrapper. Detection walks the agent's ancestors here,
+        // while the agent is still running and its launcher process is still alive; the id is
+        // replayed through `agents.launchers` at resume time. #10494
+        let externalLauncher = fallbackPID.flatMap { fallbackPID in
+            externalAgentLaunchers(workingDirectory: workingDirectory).detectedLauncher(
+                agentPID: pid_t(fallbackPID),
+                kind: fallbackKind,
+                parentPID: { self.parentPID(of: $0) },
+                argv: { self.processArguments(for: $0) }
+            )?.id
+        }
+
+        // One builder for every capture path below: the record's identity fields (launcher, external
+        // launcher, cwd, verification home) are the same in all of them, and threading each new
+        // field through four constructors is how one path silently loses it.
+        func record(
+            executablePath: String?,
+            arguments: [String],
+            environment: [String: String]?,
+            source: String
+        ) -> AgentHookLaunchCommandRecord {
+            AgentHookLaunchCommandRecord(
+                launcher: launcher,
+                externalLauncher: externalLauncher,
+                executablePath: executablePath,
+                arguments: arguments,
+                workingDirectory: workingDirectory,
+                environment: environment,
+                verificationHome: verificationHome,
+                capturedAt: Date().timeIntervalSince1970,
+                source: source
+            )
+        }
+
         // Fallback when the launch argv is genuinely UNAVAILABLE: plain `codex` with no cmux launcher
         // (no CMUX_AGENT_LAUNCH_ARGV_B64) and an unresolved/exited PID, so processArguments returns nil.
         // The argv is gone, but the agent's launch env may still carry a non-default home that
@@ -28971,16 +29035,14 @@ struct CMUXCLI {
         // the sanitizer guard below), so non-restorable invocations stay non-resumable.
         func environmentOnlyRecord() -> AgentHookLaunchCommandRecord? {
             guard !environment.isEmpty else {
-                return fallbackKind == "codex" ? AgentHookLaunchCommandRecord(launcher: launcher, executablePath: nil, arguments: [], workingDirectory: workingDirectory, environment: nil, verificationHome: verificationHome, capturedAt: Date().timeIntervalSince1970, source: "default") : nil
+                return fallbackKind == "codex"
+                    ? record(executablePath: nil, arguments: [], environment: nil, source: "default")
+                    : nil
             }
-            return AgentHookLaunchCommandRecord(
-                launcher: launcher,
+            return record(
                 executablePath: nil,
                 arguments: [],
-                workingDirectory: workingDirectory,
                 environment: environment,
-                verificationHome: verificationHome,
-                capturedAt: Date().timeIntervalSince1970,
                 source: "environment"
             )
         }
@@ -28998,18 +29060,19 @@ struct CMUXCLI {
         ) else {
             // Sanitized-away argv means a non-restorable invocation. Do not
             // replace it with an env-only fallback.
-            return AgentHookLaunchCommandRecord(launcher: launcher, executablePath: executablePath, arguments: [], workingDirectory: workingDirectory, environment: nil, verificationHome: verificationHome, capturedAt: Date().timeIntervalSince1970, source: "rejected")
+            return record(
+                executablePath: executablePath,
+                arguments: [],
+                environment: nil,
+                source: "rejected"
+            )
         }
         let source = envArguments == nil ? "process" : "environment"
 
-        return AgentHookLaunchCommandRecord(
-            launcher: launcher,
+        return record(
             executablePath: executablePath,
             arguments: sanitizedArguments,
-            workingDirectory: workingDirectory,
             environment: environment.isEmpty ? nil : environment,
-            verificationHome: verificationHome,
-            capturedAt: Date().timeIntervalSince1970,
             source: source
         )
     }
@@ -29233,19 +29296,38 @@ struct CMUXCLI {
         }
 
         guard let argv, !argv.isEmpty else { return nil }
+        // Re-supply a user-declared external launcher (#10494). Applied to the agent argv the
+        // resolution above produced, so the wrapper receives exactly the options cmux would have
+        // passed to the agent directly. The config is only read when a launcher was captured.
+        let resumeWorkingDirectory = workingDirectory ?? launchCommand?.workingDirectory
+        let externalLauncher = launchCommand?.externalLauncher.flatMap { launcherID in
+            externalAgentLaunchers(workingDirectory: resumeWorkingDirectory)
+                .resolvedLauncher(id: launcherID, kind: kind)
+        }
         return agentSurfaceResumeShellCommand(
-            argv: argv,
-            workingDirectory: workingDirectory ?? launchCommand?.workingDirectory,
+            argv: externalLauncher?.applyingResumePrefix(to: argv) ?? argv,
+            workingDirectory: resumeWorkingDirectory,
             kind: kind,
-            environment: environment
+            environment: environment,
+            // A wrapper that re-execs the agent by name loses the shim that would have been
+            // substituted into argv[0], and with it cmux's hooks; keep it first on PATH instead.
+            wrappedAgentShimEnvironmentKey: externalLauncher.flatMap { launcher in
+                launcher.includesAgentExecutable
+                    ? nil
+                    : AgentRestoreLaunch(
+                        kind: kind,
+                        sessionID: normalizedSessionId
+                    )?.wrapperShimEnvironmentKey
+            }
         )
     }
 
     private func agentSurfaceResumeShellCommand(
         argv: [String],
         workingDirectory: String?,
         kind: String,
-        environment: [String: String]?
+        environment: [String: String]?,
+        wrappedAgentShimEnvironmentKey: String? = nil
     ) -> String {
         var commandParts: [String] = []
         commandParts.append(contentsOf: argv)
@@ -29275,6 +29357,12 @@ struct CMUXCLI {
                 environment: environment
             )
         }
+        if let wrappedAgentShimEnvironmentKey {
+            command = AgentExternalLauncherRegistry.portableShellCommandRoutingWrappedAgentThroughShim(
+                posixCommand: command,
+                shimEnvironmentKey: wrappedAgentShimEnvironmentKey
+            )
+        }
         if let cwd {
             let quotedCwd = cliShellQuote(cwd)
             // No POSIX `{ …; }` grouping: the binding runs verbatim in the login shell,