Accept configured peer URLs in cross-gateway session routing

This path resolves gateway.peers and then immediately calls resolveGatewayOptions(peerOpts), but resolveGatewayOptions still enforces gatewayUrl to be loopback or gateway.remote.url via validateGatewayUrlOverrideForAgentTools (src/agents/tools/gateway.ts). In practice, a peer like wss://imac.local:18789 is rejected with gatewayUrl override rejected, so the new gateway parameter cannot reach most configured peers (same failure pattern also applies to sessions_spawn).

Useful? React with 👍 / 👎.

Include idempotencyKey when forwarding remote sessions_spawn

The remote sessions_spawn fast path forwards to the gateway agent method, but this request body omits idempotencyKey. The gateway protocol requires idempotencyKey for agent requests (AgentParamsSchema), so any sessions_spawn call with gateway/gatewayUrl will be rejected as invalid params before the remote agent run starts.

Useful? React with 👍 / 👎.

resolveGatewayOptions rejects all peer URLs — cross-gateway routing will always fail

resolveGatewayOptions calls validateGatewayUrlOverrideForAgentTools internally, which only permits two categories of URL:

1. Loopback addresses (127.0.0.1, localhost, [::1]) on the configured local port
2. Exactly the URL in gateway.remote.url

Any peer URL like wss://imac.local:18789 will cause validateGatewayUrlOverrideForAgentTools to throw:

"gatewayUrl override rejected. Allowed: ws(s) loopback on port X ..."

This error is not caught here — it will propagate as an unhandled exception and break the tool call. The same problem exists in sessions-spawn-tool.ts at the equivalent resolveGatewayOptions(peerOpts) call.

The PR description states "peer URLs are validated through existing resolveGatewayOptions()", but that function's allowlist was designed for a single remote gateway, not for arbitrary peer URLs. The cross-gateway feature will be entirely broken for any peer that is not also the configured gateway.remote.url.

The fix is to bypass resolveGatewayOptions for peer URLs that have already been validated by the config schema, and call callGateway directly with the resolved URL and token from peerOpts, similar to what the local path does but without the URL re-validation step.

This is a comment left during a code review.
Path: src/agents/tools/sessions-send-tool.ts
Line: 88

Comment:
**`resolveGatewayOptions` rejects all peer URLs — cross-gateway routing will always fail**

`resolveGatewayOptions` calls `validateGatewayUrlOverrideForAgentTools` internally, which only permits two categories of URL:
1. Loopback addresses (`127.0.0.1`, `localhost`, `[::1]`) on the configured local port
2. Exactly the URL in `gateway.remote.url`

Any peer URL like `wss://imac.local:18789` will cause `validateGatewayUrlOverrideForAgentTools` to throw:
```
"gatewayUrl override rejected. Allowed: ws(s) loopback on port X ..."
```

This error is **not caught** here — it will propagate as an unhandled exception and break the tool call. The same problem exists in `sessions-spawn-tool.ts` at the equivalent `resolveGatewayOptions(peerOpts)` call.

The PR description states "peer URLs are validated through existing `resolveGatewayOptions()`", but that function's allowlist was designed for a single remote gateway, not for arbitrary peer URLs. The cross-gateway feature will be entirely broken for any peer that is not also the configured `gateway.remote.url`.

The fix is to bypass `resolveGatewayOptions` for peer URLs that have already been validated by the config schema, and call `callGateway` directly with the resolved URL and token from `peerOpts`, similar to what the local path does but without the URL re-validation step.

How can I resolve this? If you propose a fix, please make it concise.

Silent token resolution failure produces misleading auth errors

When resolveSecretInputString fails (e.g., because ${env:IMAC_GATEWAY_TOKEN} references an env var that isn't set), the error is silently swallowed. resolvedToken remains undefined, and the peer call proceeds without auth. The remote gateway will then reject the request with an authentication error that gives the user no indication that their token config is broken.

While the comment says "non-fatal if the peer gateway doesn't require auth", this hides a clear configuration error (a missing env var) behind a confusing downstream failure. At a minimum, the resolution failure should be surfaced as a warning in the thrown error message or re-thrown when the result is undefined and a token was explicitly configured.

This is a comment left during a code review.
Path: src/agents/tools/gateway-peer.ts
Line: 48-51

Comment:
**Silent token resolution failure produces misleading auth errors**

When `resolveSecretInputString` fails (e.g., because `${env:IMAC_GATEWAY_TOKEN}` references an env var that isn't set), the error is silently swallowed. `resolvedToken` remains `undefined`, and the peer call proceeds without auth. The remote gateway will then reject the request with an authentication error that gives the user no indication that their token config is broken.

While the comment says "non-fatal if the peer gateway doesn't require auth", this hides a clear configuration error (a missing env var) behind a confusing downstream failure. At a minimum, the resolution failure should be surfaced as a warning in the thrown error message or re-thrown when the result is `undefined` and a token was explicitly configured.

How can I resolve this? If you propose a fix, please make it concise.

Cross-gateway spawn silently drops all spawn-specific parameters

When peerOpts is set, only message, sessionKey, label, deliver, channel, and inputProvenance are forwarded to the remote gateway. All of the following caller-provided parameters are silently ignored:

• runtime (subagent vs acp)
• model
• thinking
• cwd
• runTimeoutSeconds / timeoutSeconds
• mode (run vs session)
• cleanup
• sandbox
• streamTo
• attachments / attachAs
• resumeSessionId

A caller doing sessions_spawn(task="...", agentId="pepper", gateway="studio", runtime="acp", model="gpt-4o") will silently get whatever defaults the remote gateway applies, not the requested runtime or model. If these parameters are intentionally not supported for cross-gateway spawning, the tool should validate and reject their presence explicitly (like UNSUPPORTED_SESSIONS_SPAWN_PARAM_KEYS does for channel params) rather than silently dropping them.

This is a comment left during a code review.
Path: src/agents/tools/sessions-spawn-tool.ts
Line: 127-146

Comment:
**Cross-gateway spawn silently drops all spawn-specific parameters**

When `peerOpts` is set, only `message`, `sessionKey`, `label`, `deliver`, `channel`, and `inputProvenance` are forwarded to the remote gateway. All of the following caller-provided parameters are silently ignored:

- `runtime` (subagent vs acp)
- `model`
- `thinking`
- `cwd`
- `runTimeoutSeconds` / `timeoutSeconds`
- `mode` (run vs session)
- `cleanup`
- `sandbox`
- `streamTo`
- `attachments` / `attachAs`
- `resumeSessionId`

A caller doing `sessions_spawn(task="...", agentId="pepper", gateway="studio", runtime="acp", model="gpt-4o")` will silently get whatever defaults the remote gateway applies, not the requested `runtime` or `model`. If these parameters are intentionally not supported for cross-gateway spawning, the tool should validate and reject their presence explicitly (like `UNSUPPORTED_SESSIONS_SPAWN_PARAM_KEYS` does for channel params) rather than silently dropping them.

How can I resolve this? If you propose a fix, please make it concise.

No URL format validation on gateway.peers[*].url

The url field is accepted as any non-empty string. A misconfigured value like "http://imac.local:18789" (wrong protocol) or "imac.local:18789" (missing scheme) will only fail at runtime when the connection is attempted, producing a confusing error rather than a clear config validation message.

Consider adding a .url() or a refine check for ws:// / wss:// prefix to catch misconfigurations at startup:

This is a comment left during a code review.
Path: src/config/zod-schema.ts
Line: 813

Comment:
**No URL format validation on `gateway.peers[*].url`**

The `url` field is accepted as any non-empty string. A misconfigured value like `"http://imac.local:18789"` (wrong protocol) or `"imac.local:18789"` (missing scheme) will only fail at runtime when the connection is attempted, producing a confusing error rather than a clear config validation message.

Consider adding a `.url()` or a `refine` check for `ws://` / `wss://` prefix to catch misconfigurations at startup:
```suggestion
                url: z.string().refine(
                  (v) => v.startsWith("ws://") || v.startsWith("wss://"),
                  { message: "gateway peer url must start with ws:// or wss://" },
                ),
```

How can I resolve this? If you propose a fix, please make it concise.

Reject tokenless peers before routing to overridden gateway

This helper returns peer overrides even when no token is available (gatewayToken resolves to undefined), and both new cross-gateway paths pass that straight into callGateway. callGateway treats any explicit url as an override and requires explicit credentials (ensureExplicitGatewayAuth), so peer entries without a token will fail with "gateway url override requires explicit credentials" before the remote request is attempted. That makes the new optional gateway.peers.<name>.token behavior non-functional for tokenless peers.

Useful? React with 👍 / 👎.

Preserve sessionKey/label exclusivity in remote sessions_send

The remote branch only checks for the "neither provided" case, so when both sessionKey and label are sent it silently prefers sessionKey and skips label resolution. The local branch still rejects this combination, so cross-gateway behavior becomes inconsistent and can route messages to an unintended session instead of surfacing an input error.

Useful? React with 👍 / 👎.