fix(proxydial): bind the proxy exemption to the route the transport chose

Asking the Proxy function a question of our own invention answered for a
request the transport never made. With NO_PROXY excluding a host, the real
request to that host goes direct while a synthetic probe still comes back
proxied, so a direct dial whose address happened to equal the configured
proxy endpoint skipped the guard and reached whatever the name resolved to
at connect time. A probe on the previous head dials rebind.example:80 with
zero safety lookups; the guard now runs and refuses its private answer.
Host-dependent proxy callbacks make the mismatch general, and no spelling
of the probe host closes it, because the two calls are about different
requests.

The decision is now recorded where it is made. proxydial.Transport wraps
the transport, asks its Proxy function about the actual request, and puts
the answer in that request's context; the transport derives the dial
context from the request context, so the dialer reads back the route this
very connection is being opened for. Per-request, so concurrent requests
cannot overwrite each other, and the context key is unexported so nothing
outside the package can plant one.

Address matching is gone with it. A transport opens one connection dial,
and when a proxy is selected that dial goes to the proxy, so the recorded
route already identifies the dial. Comparing the address on top could only
disagree with the transport, which is what a Unicode proxy hostname did:
Go dials xn--bro-hoa.example while the URL still spells it as configured,
and the proxy was refused as an ordinary private address. Both spellings
are now one endpoint with no comparison to get wrong.

Documents where destination enforcement ends: with a proxy configured, the
target hostname is sent to the proxy and the proxy resolves it, so the
local pre-request checks no longer bind the address that is reached. A
forward proxy already sees and can rewrite every request through it, so
that trust comes with configuring one; the alternative is refusing to use
proxies at all, which is the outage in #569.

README.md

@@ -273,6 +273,19 @@ zero sandbox grants list
 Zero includes local file/search/edit/shell tools, `web_fetch` for public URLs,
 and MCP support for additional tools.
 
+`web_fetch` refuses loopback, private and other special-use addresses: it checks
+the URL before asking permission, resolves the host, and dials the address it
+validated so a name cannot resolve to something else in between.
+
+If `HTTP_PROXY`/`HTTPS_PROXY` is set, `web_fetch` and the provider connectivity
+probe use it, and that last step changes: the proxy is dialed and the target
+hostname is sent to it, so the proxy decides which address the request actually
+reaches. The URL is still checked and resolved locally first, but a proxy that
+answers differently can reach a private service. A forward proxy already sees
+and can rewrite every request through it, so this is the trust you accept by
+configuring one. Leave the variables unset for the checks to be enforced end to
+end.
+
 For local dev servers, use shell commands such as `curl` through `exec_command`
 so the normal sandbox and permission policy applies. Long-running commands stay
 attached to a background terminal session and can be listed or stopped from the

docs/HOW_ZERO_WORKS.md

@@ -627,7 +627,12 @@ Core tool groups include:
   skills, `ask_user`, permission requests.
 - **Write tools**: `write_file`, `edit_file`, `apply_patch`, `update_plan`.
 - **Shell tools**: `exec_command`, `write_stdin`, legacy `bash`.
-- **Network tools**: `web_fetch` and optional web search backend.
+- **Network tools**: `web_fetch` and optional web search backend. `web_fetch`
+  validates the URL before the permission prompt, refuses loopback/private/
+  special-use addresses, and dials the address it resolved. With
+  `HTTP_PROXY`/`HTTPS_PROXY` set, the proxy is dialed instead and resolves the
+  target itself, so destination enforcement ends at the proxy; see the note in
+  the README.
 - **Local-control tools**: config-gated wrappers for browser, terminal, desktop,
   and artifact helpers backed by packages such as `internal/localcontrol` and
   `internal/browser`.

internal/acp/permission.go

@@ -142,13 +142,15 @@ func actionOffered(optionID string, offered []PermissionOption) bool {
 // session/request_permission request from a ZERO permission request.
 func permissionToolCall(req agent.PermissionRequest) ToolCallUpdate {
 	args := marshalArgs(req.Args)
-	return ToolCallUpdate{
+	upd := ToolCallUpdate{
 		ToolCallID: req.ToolCallID,
 		Title:      toolTitle(req.ToolName, string(args)),
 		Kind:       toolKindFor(req.ToolName),
 		Status:     ToolStatusPending,
 		RawInput:   rawInputBytes(args),
 	}
+	attachBrowserToolDetails(&upd, req.ToolName)
+	return upd
 }
 
 func marshalArgs(args map[string]any) []byte {

internal/acp/permission_test.go

@@ -82,3 +82,17 @@ func TestPermissionToolCall(t *testing.T) {
 		t.Error("expected rawInput from args")
 	}
 }
+
+func TestPermissionToolCallKeepsTheBrowserDescriptor(t *testing.T) {
+	call := permissionToolCall(agent.PermissionRequest{
+		ToolCallID: "browser-1",
+		ToolName:   "browser_connect",
+		Args:       map[string]any{"target": "127.0.0.1:9222"},
+	})
+	if got := browserDescriptor(t, call); got != (BrowserToolDetails{Version: 1, Command: "connect"}) {
+		t.Fatalf("browser descriptor = %#v", got)
+	}
+	if call.Title != "browser connect" {
+		t.Fatalf("title = %q", call.Title)
+	}
+}

internal/acp/translate.go

@@ -2,7 +2,9 @@ package acp
 
 import (
 	"encoding/json"
+	"net/url"
 	"strings"
+	"unicode"
 	"unicode/utf8"
 
 	"github.com/Gitlawb/zero/internal/agent"
@@ -44,12 +46,125 @@ func toolKindFor(name string) string {
 
 // toolTitle builds a concise human title, e.g. "read_file src/main.go".
 func toolTitle(name, rawArgs string) string {
+	if browser, ok := browserToolDetails(name); ok {
+		return browserToolTitle(browser.Command, rawArgs)
+	}
 	if hint := primaryArgHint(rawArgs); hint != "" {
 		return name + " " + hint
 	}
 	return name
 }
 
+// browserToolDetails identifies ZERO's local browser helpers without treating
+// similarly named MCP tools as browser automation. The descriptor intentionally
+// contains no request data: ACP tool input is already protocol-visible, but a
+// durable UI must not need to retain text, local CDP targets, or full URLs just
+// to recognise the browser operation.
+func browserToolDetails(name string) (*BrowserToolDetails, bool) {
+	const prefix = "browser_"
+	command, ok := strings.CutPrefix(name, prefix)
+	if !ok {
+		return nil, false
+	}
+	switch command {
+	case "install", "launch", "connect", "open", "snapshot", "click", "type", "press", "action":
+		return &BrowserToolDetails{Version: 1, Command: command}, true
+	default:
+		return nil, false
+	}
+}
+
+const zeroBrowserMetaKey = "github.com/Gitlawb/zero/browser"
+
+// attachBrowserToolDetails stores ZERO's browser descriptor in ACP's reserved
+// extension channel. Keeping this in one helper prevents start, result, and
+// permission payloads from drifting onto different wire shapes.
+func attachBrowserToolDetails(update *ToolCallUpdate, name string) {
+	browser, ok := browserToolDetails(name)
+	if !ok {
+		return
+	}
+	raw, err := json.Marshal(browser)
+	if err != nil {
+		return
+	}
+	update.Meta = map[string]json.RawMessage{zeroBrowserMetaKey: raw}
+}
+
+// browserToolTitle avoids putting browser_type text, an attached DevTools
+// endpoint, or a URL query/fragment in a tool-card title. Those values can
+// carry credentials or session data; the UI only needs the operation and, for
+// navigation, a human-recognisable origin.
+func browserToolTitle(command, rawArgs string) string {
+	switch command {
+	case "action":
+		action, ok := exactJSONStringArg(rawArgs, "command")
+		if !ok {
+			return "browser action"
+		}
+		if action, ok := tools.NormalizedBrowserActionCommand(action); ok {
+			return "browser action " + action
+		}
+		return "browser action"
+	case "open":
+		rawURL, ok := exactJSONStringArg(rawArgs, "url")
+		if !ok {
+			return "browser open"
+		}
+		normalized, err := tools.NormalizeBrowserOpenURL(rawURL)
+		if err != nil {
+			return "browser open"
+		}
+		u, err := url.Parse(normalized)
+		if err != nil || u.Scheme == "" || u.Host == "" {
+			return "browser open"
+		}
+		origin := u.Scheme + "://" + u.Host
+		if !browserTitleTextSafe(origin) {
+			return "browser open"
+		}
+		return "browser open " + truncateHint(origin)
+	default:
+		return "browser " + command
+	}
+}
+
+// browserTitleTextSafe validates text after URL parsing has decoded escaped
+// UTF-8 in the host. Valid UTF-8 alone is not presentation-safe: control,
+// format/bidi, and line/paragraph separator runes can reorder or split the
+// permission label shown to a user. The execution URL remains unchanged.
+func browserTitleTextSafe(text string) bool {
+	if !utf8.ValidString(text) {
+		return false
+	}
+	for _, r := range text {
+		if unicode.IsControl(r) || unicode.Is(unicode.Cf, r) || unicode.Is(unicode.Zl, r) || unicode.Is(unicode.Zp, r) {
+			return false
+		}
+	}
+	return true
+}
+
+// exactJSONStringArg mirrors ZERO's map-based tool argument decoding: only the
+// exact JSON key is considered, and a non-string value is invalid. In
+// particular, an incidental "URL" key must not change a permission title when
+// browser_open will only read "url".
+func exactJSONStringArg(rawArgs, key string) (string, bool) {
+	var args map[string]json.RawMessage
+	if json.Unmarshal([]byte(rawArgs), &args) != nil {
+		return "", false
+	}
+	raw, ok := args[key]
+	if !ok {
+		return "", false
+	}
+	var value string
+	if json.Unmarshal(raw, &value) != nil {
+		return "", false
+	}
+	return value, true
+}
+
 // primaryArgHint extracts the most relevant argument (path/pattern/command) from
 // raw JSON arguments. Best-effort; returns "" when it can't parse.
 func primaryArgHint(rawArgs string) string {
@@ -89,7 +204,7 @@ func rawInput(args string) json.RawMessage {
 // toolCallStart maps an advertised ZERO tool call to the initial ACP "tool_call"
 // update (status in_progress — ZERO executes immediately after advertising).
 func toolCallStart(call agent.ToolCall) ToolCallUpdate {
-	return ToolCallUpdate{
+	upd := ToolCallUpdate{
 		SessionUpdate: UpdateToolCall,
 		ToolCallID:    call.ID,
 		Title:         toolTitle(call.Name, call.Arguments),
@@ -97,6 +212,8 @@ func toolCallStart(call agent.ToolCall) ToolCallUpdate {
 		Status:        ToolStatusInProgress,
 		RawInput:      rawInput(call.Arguments),
 	}
+	attachBrowserToolDetails(&upd, call.Name)
+	return upd
 }
 
 // toolCallResult maps a finished ZERO tool result to a "tool_call_update".
@@ -116,6 +233,7 @@ func toolCallResult(result agent.ToolResult) ToolCallUpdate {
 	if locs := toolResultLocations(result); len(locs) > 0 {
 		upd.Locations = locs
 	}
+	attachBrowserToolDetails(&upd, result.Name)
 	return upd
 }
 

internal/acp/translate_test.go

@@ -1,14 +1,29 @@
 package acp
 
 import (
+	"encoding/json"
 	"strings"
 	"testing"
+	"unicode"
 	"unicode/utf8"
 
 	"github.com/Gitlawb/zero/internal/agent"
 	"github.com/Gitlawb/zero/internal/tools"
 )
 
+func browserDescriptor(t *testing.T, update ToolCallUpdate) BrowserToolDetails {
+	t.Helper()
+	raw, ok := update.Meta[zeroBrowserMetaKey]
+	if !ok {
+		t.Fatalf("browser metadata = %#v, want %q", update.Meta, zeroBrowserMetaKey)
+	}
+	var details BrowserToolDetails
+	if err := json.Unmarshal(raw, &details); err != nil {
+		t.Fatalf("decode browser metadata: %v", err)
+	}
+	return details
+}
+
 func TestAgentMessageAndThoughtChunks(t *testing.T) {
 	m := agentMessageChunk("hello")
 	if m.SessionUpdate != UpdateAgentMessageChunk || m.Content.Type != "text" || m.Content.Text != "hello" {
@@ -56,6 +71,217 @@ func TestToolTitleAndHint(t *testing.T) {
 	}
 }
 
+func TestBrowserToolUpdatesAreStructuredAndPresentationSafe(t *testing.T) {
+	start := toolCallStart(agent.ToolCall{
+		ID:        "browser-1",
+		Name:      "browser_open",
+		Arguments: `{"url":"https://example.com/settings?token=not-for-a-title#account"}`,
+	})
+	if got := browserDescriptor(t, start); got != (BrowserToolDetails{Version: 1, Command: "open"}) {
+		t.Fatalf("browser descriptor = %#v, want open", got)
+	}
+	if start.Title != "browser open https://example.com" {
+		t.Fatalf("browser title = %q", start.Title)
+	}
+	if strings.Contains(start.Title, "token=") || strings.Contains(start.Title, "#account") {
+		t.Fatalf("browser title leaked URL-sensitive data: %q", start.Title)
+	}
+	encoded, err := json.Marshal(start)
+	if err != nil {
+		t.Fatal(err)
+	}
+	var wire struct {
+		Meta map[string]json.RawMessage `json:"_meta"`
+	}
+	if err := json.Unmarshal(encoded, &wire); err != nil {
+		t.Fatal(err)
+	}
+	if _, ok := wire.Meta[zeroBrowserMetaKey]; !ok {
+		t.Fatalf("browser wire metadata = %#v", wire.Meta)
+	}
+
+	typed := toolCallStart(agent.ToolCall{
+		ID:        "browser-2",
+		Name:      "browser_type",
+		Arguments: `{"ref":"email","text":"[email protected]"}`,
+	})
+	if got := browserDescriptor(t, typed); got.Command != "type" {
+		t.Fatalf("browser type descriptor = %#v", got)
+	}
+	if typed.Title != "browser type" || strings.Contains(typed.Title, "[email protected]") {
+		t.Fatalf("browser type title = %q", typed.Title)
+	}
+
+	action := toolCallStart(agent.ToolCall{
+		ID:        "browser-3",
+		Name:      "browser_action",
+		Arguments: `{"command":"keyboard_insert_text","args":["[email protected]"]}`,
+	})
+	if action.Title != "browser action keyboard_insert_text" {
+		t.Fatalf("browser action title = %q", action.Title)
+	}
+
+	result := toolCallResult(agent.ToolResult{
+		ToolCallID: "browser-2",
+		Name:       "browser_type",
+		Status:     tools.StatusOK,
+	})
+	if got := browserDescriptor(t, result); got.Command != "type" {
+		t.Fatalf("browser result descriptor = %#v", got)
+	}
+}
+
+func TestBrowserDescriptorSurvivesProtocolShapedRoundTrip(t *testing.T) {
+	updates := []ToolCallUpdate{
+		toolCallStart(agent.ToolCall{
+			ID:        "start",
+			Name:      "browser_open",
+			Arguments: `{"url":"https://user:[email protected]/private?token=secret#fragment"}`,
+		}),
+		toolCallResult(agent.ToolResult{
+			ToolCallID: "result",
+			Name:       "browser_type",
+			Status:     tools.StatusOK,
+		}),
+		permissionToolCall(agent.PermissionRequest{
+			ToolCallID: "permission",
+			ToolName:   "browser_connect",
+			Args:       map[string]any{"target": "127.0.0.1:9222"},
+		}),
+	}
+
+	type protocolToolCallUpdate struct {
+		SessionUpdate string                     `json:"sessionUpdate,omitempty"`
+		ToolCallID    string                     `json:"toolCallId"`
+		Title         string                     `json:"title,omitempty"`
+		Kind          string                     `json:"kind,omitempty"`
+		Status        string                     `json:"status,omitempty"`
+		RawInput      json.RawMessage            `json:"rawInput,omitempty"`
+		Content       []ToolCallContent          `json:"content,omitempty"`
+		Locations     []ToolCallLocation         `json:"locations,omitempty"`
+		Meta          map[string]json.RawMessage `json:"_meta,omitempty"`
+	}
+
+	for _, update := range updates {
+		encoded, err := json.Marshal(update)
+		if err != nil {
+			t.Fatal(err)
+		}
+		var root map[string]json.RawMessage
+		if err := json.Unmarshal(encoded, &root); err != nil {
+			t.Fatal(err)
+		}
+		if _, ok := root["browser"]; ok {
+			t.Fatalf("browser descriptor escaped ACP _meta: %s", encoded)
+		}
+
+		var protocol protocolToolCallUpdate
+		if err := json.Unmarshal(encoded, &protocol); err != nil {
+			t.Fatal(err)
+		}
+		forwarded, err := json.Marshal(protocol)
+		if err != nil {
+			t.Fatal(err)
+		}
+		var roundTripped ToolCallUpdate
+		if err := json.Unmarshal(forwarded, &roundTripped); err != nil {
+			t.Fatal(err)
+		}
+		details := browserDescriptor(t, roundTripped)
+		if details.Version != 1 || details.Command == "" {
+			t.Fatalf("round-tripped browser descriptor = %#v", details)
+		}
+		descriptorJSON := string(roundTripped.Meta[zeroBrowserMetaKey])
+		for _, secret := range []string{"password", "private", "token", "fragment", "127.0.0.1", "9222"} {
+			if strings.Contains(descriptorJSON, secret) {
+				t.Fatalf("browser descriptor leaked %q: %s", secret, descriptorJSON)
+			}
+		}
+	}
+}
+
+func TestBrowserPermissionTitlesMirrorSafeToolArguments(t *testing.T) {
+	if got := browserToolTitle("open", `{"url":"evil.example.test/pay?token=hidden#fragment"}`); got != "browser open https://evil.example.test" {
+		t.Fatalf("bare-host title = %q", got)
+	}
+	if got := browserToolTitle("open", `{"URL":"https://different.example.test"}`); got != "browser open" {
+		t.Fatalf("case-variant URL title = %q", got)
+	}
+	if got := browserToolTitle("open", `{"URL":"https://different.example.test","url":"https://actual.example.test/path"}`); got != "browser open https://actual.example.test" {
+		t.Fatalf("exact URL key title = %q", got)
+	}
+	if got := browserToolTitle("action", `{"command":"not an action"}`); got != "browser action" {
+		t.Fatalf("unknown browser action title = %q", got)
+	}
+
+	longHost := "https://" + strings.Repeat("a", 200) + ".example.test/path?token=hidden"
+	title := browserToolTitle("open", `{"url":"`+longHost+`"}`)
+	if !utf8.ValidString(title) || utf8.RuneCountInString(title) > len("browser open ")+61 || strings.Contains(title, "token=") {
+		t.Fatalf("bounded browser origin title = %q", title)
+	}
+}
+
+func TestBrowserOpenTitlesRejectDecodedUnicodePresentationControls(t *testing.T) {
+	for _, rawURL := range []string{
+		"https://safe.example%E2%80%AEevil.test/path",
+		"https://safe.example%E2%81%A6evil.test/path",
+		"https://safe.example%C2%85evil.test/path",
+		"https://safe.example%E2%80%A8evil.test/path",
+		"https://safe.example%E2%80%A9evil.test/path",
+	} {
+		t.Run(rawURL, func(t *testing.T) {
+			normalized, err := tools.NormalizeBrowserOpenURL(rawURL)
+			if err != nil {
+				t.Fatalf("execution URL rejected: %v", err)
+			}
+			if normalized != rawURL {
+				t.Fatalf("execution URL = %q, want unchanged %q", normalized, rawURL)
+			}
+
+			args, err := json.Marshal(map[string]any{"url": rawURL})
+			if err != nil {
+				t.Fatal(err)
+			}
+			updates := []ToolCallUpdate{
+				toolCallStart(agent.ToolCall{ID: "start", Name: "browser_open", Arguments: string(args)}),
+				permissionToolCall(agent.PermissionRequest{ToolCallID: "permission", ToolName: "browser_open", Args: map[string]any{"url": rawURL}}),
+			}
+			for _, update := range updates {
+				encoded, err := json.Marshal(update)
+				if err != nil {
+					t.Fatal(err)
+				}
+				var decoded ToolCallUpdate
+				if err := json.Unmarshal(encoded, &decoded); err != nil {
+					t.Fatal(err)
+				}
+				if decoded.Title != "browser open" {
+					t.Fatalf("unsafe browser title survived wire round trip: %q", decoded.Title)
+				}
+				for _, r := range decoded.Title {
+					if unicode.IsControl(r) || unicode.Is(unicode.Cf, r) || unicode.Is(unicode.Zl, r) || unicode.Is(unicode.Zp, r) {
+						t.Fatalf("browser title contains unsafe presentation rune %U: %q", r, decoded.Title)
+					}
+				}
+			}
+		})
+	}
+}
+
+func TestBrowserDescriptorDoesNotClaimSimilarlyNamedMCPTools(t *testing.T) {
+	start := toolCallStart(agent.ToolCall{ID: "mcp-1", Name: "browser_plugin_open", Arguments: `{}`})
+	if len(start.Meta) != 0 {
+		t.Fatalf("MCP-like tool received built-in browser metadata: %#v", start.Meta)
+	}
+	encoded, err := json.Marshal(start)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if strings.Contains(string(encoded), `"browser"`) {
+		t.Fatalf("non-browser tool encoded browser field: %s", encoded)
+	}
+}
+
 func TestToolCallStart(t *testing.T) {
 	upd := toolCallStart(agent.ToolCall{ID: "tc1", Name: "read_file", Arguments: `{"path":"a.go"}`})
 	if upd.SessionUpdate != UpdateToolCall {

internal/acp/types.go

@@ -210,6 +210,21 @@ type ToolCallUpdate struct {
 	RawInput      json.RawMessage    `json:"rawInput,omitempty"`
 	Content       []ToolCallContent  `json:"content,omitempty"`
 	Locations     []ToolCallLocation `json:"locations,omitempty"`
+	// Meta is ACP's extension channel. ZERO-owned values must remain beneath a
+	// namespaced key so protocol-shaped clients can preserve them while decoding
+	// and re-encoding a tool call.
+	Meta map[string]json.RawMessage `json:"_meta,omitempty"`
+}
+
+// BrowserToolDetails identifies the browser helper operation behind a tool
+// call. Version is the schema version for this optional ZERO extension;
+// Command is one of install, launch, connect, open, snapshot, click, type,
+// press, or action. Future fields must remain display-safe and must not
+// include browser profile data, cookies, typed text, URL paths/queries, or
+// DevTools endpoints.
+type BrowserToolDetails struct {
+	Version int    `json:"version"`
+	Command string `json:"command"`
 }
 
 // ToolCallContent is a tool call's rendered output. ZERO emits "content" (a

internal/mcp/oauth.go

@@ -63,8 +63,9 @@ func tokenToStored(t oauth.Token) StoredToken {
 }
 
 // OAuthConfig describes how to authenticate to a remote MCP server using OAuth.
-// Endpoints may be discovered from the server's metadata document; explicit
-// values here override or fill in anything discovery cannot provide.
+// Endpoints may be discovered through RFC 9728 protected-resource metadata and
+// RFC 8414 authorization-server metadata; explicit values override or fill in
+// anything discovery cannot provide.
 type OAuthConfig struct {
 	ClientID              string
 	ClientSecret          string
@@ -85,6 +86,11 @@ type authServerMetadata struct {
 	TokenEndpoint         string   `json:"token_endpoint"`
 	RegistrationEndpoint  string   `json:"registration_endpoint"`
 	ScopesSupported       []string `json:"scopes_supported"`
+
+	protectedResourceURL         string
+	protectAuthorizationEndpoint bool
+	protectTokenEndpoint         bool
+	protectRegistrationEndpoint  bool
 }
 
 // pkceParams holds a PKCE verifier/challenge pair.
@@ -120,7 +126,7 @@ type authorizationFlow struct {
 // discoverAuthorizationServer fetches the RFC 8414 authorization server metadata
 // at the well-known path under baseURL, via the shared engine.
 func discoverAuthorizationServer(ctx context.Context, client *http.Client, baseURL string) (authServerMetadata, error) {
-	meta, err := oauth.DiscoverAuthorizationServer(ctx, client, baseURL)
+	meta, err := oauth.DiscoverAuthorizationServer(ctx, withoutDiscoveryRedirects(client), baseURL)
 	if err != nil {
 		return authServerMetadata{}, err
 	}
@@ -133,10 +139,9 @@ func discoverAuthorizationServer(ctx context.Context, client *http.Client, baseU
 	}, nil
 }
 
-// validateResolvedEndpoints applies the shared https/loopback endpoint rule to
-// every non-empty endpoint in the resolved metadata — configured or discovered
-// alike — so discovery metadata can never downgrade an MCP login to an insecure
-// or attacker-controlled authorization, token, or registration endpoint.
+// validateResolvedEndpoints applies the shared https/loopback scheme rule to
+// every non-empty endpoint in the resolved metadata. Protected-resource
+// discovery adds its stricter provenance-aware network rule below.
 func validateResolvedEndpoints(metadata authServerMetadata) error {
 	for _, ep := range []struct{ kind, url string }{
 		{"authorization", metadata.AuthorizationEndpoint},
@@ -153,9 +158,43 @@ func validateResolvedEndpoints(metadata authServerMetadata) error {
 	return nil
 }
 
-// resolveAuthorizationServer discovers metadata and applies explicit config
-// overrides. Configured endpoints take precedence over discovered ones, and act
-// as a fallback when discovery fails or omits a value.
+func validateProtectedDiscoveredEndpoints(ctx context.Context, metadata authServerMetadata) error {
+	if metadata.protectedResourceURL == "" {
+		return nil
+	}
+	policy, err := newOAuthDiscoveryNetworkPolicy(metadata.protectedResourceURL)
+	if err != nil {
+		return err
+	}
+	for _, endpoint := range []struct {
+		kind      string
+		url       string
+		protected bool
+	}{
+		{kind: "authorization", url: metadata.AuthorizationEndpoint, protected: metadata.protectAuthorizationEndpoint},
+		{kind: "token", url: metadata.TokenEndpoint, protected: metadata.protectTokenEndpoint},
+		{kind: "registration", url: metadata.RegistrationEndpoint, protected: metadata.protectRegistrationEndpoint},
+	} {
+		if !endpoint.protected || strings.TrimSpace(endpoint.url) == "" {
+			continue
+		}
+		parsed, parseErr := url.Parse(endpoint.url)
+		if parseErr != nil || parsed.Hostname() == "" {
+			return fmt.Errorf("mcp oauth: %s endpoint: %w", endpoint.kind, errUnsafeOAuthDiscoveryTarget)
+		}
+		if err := policy.validateLiteralHost(parsed.Hostname()); err != nil {
+			return fmt.Errorf("mcp oauth: %s endpoint: %w", endpoint.kind, err)
+		}
+		if _, err := policy.resolve(ctx, parsed.Hostname()); err != nil {
+			return fmt.Errorf("mcp oauth: %s endpoint: %w", endpoint.kind, err)
+		}
+	}
+	return nil
+}
+
+// resolveAuthorizationServer follows protected-resource metadata when the MCP
+// endpoint advertises it, falls back to direct authorization-server discovery
+// for legacy providers, then applies explicit config overrides.
 func resolveAuthorizationServer(ctx context.Context, client *http.Client, baseURL string, cfg OAuthConfig) (authServerMetadata, error) {
 	// When the config supplies both the authorization and token endpoints
 	// directly, skip network discovery entirely: there is nothing to discover,
@@ -174,17 +213,40 @@ func resolveAuthorizationServer(ctx context.Context, client *http.Client, baseUR
 		return metadata, nil
 	}
 
+	discoveryClient := withoutDiscoveryRedirects(client)
 	discoveryBase := strings.TrimSpace(cfg.IssuerURL)
+	protectedResourceDiscovery := false
 	if discoveryBase == "" {
-		discoveryBase = baseURL
+		issuer, found, protectedErr := discoverProtectedResourceAuthorizationServer(ctx, discoveryClient, baseURL)
+		if protectedErr != nil {
+			return authServerMetadata{}, protectedErr
+		}
+		if found {
+			discoveryBase = issuer
+			protectedResourceDiscovery = true
+			discoveryClient, protectedErr = newAdvertisedOAuthDiscoveryClient(discoveryClient, baseURL)
+			if protectedErr != nil {
+				return authServerMetadata{}, protectedErr
+			}
+		} else {
+			discoveryBase = baseURL
+		}
 	}
 
-	metadata, err := discoverAuthorizationServer(ctx, client, discoveryBase)
+	metadata, err := discoverAuthorizationServer(ctx, discoveryClient, discoveryBase)
 	if err != nil {
 		// Discovery failures are non-fatal when the config supplies the endpoints
 		// directly; otherwise surface the discovery error.
 		metadata = authServerMetadata{}
 	}
+	if protectedResourceDiscovery {
+		if strings.TrimSpace(metadata.Issuer) == "" {
+			return authServerMetadata{}, errors.New("mcp oauth: authorization server metadata is missing its required issuer")
+		}
+		if metadata.Issuer != discoveryBase {
+			return authServerMetadata{}, errors.New("mcp oauth: authorization server metadata issuer does not match protected resource metadata")
+		}
+	}
 
 	if endpoint := strings.TrimSpace(cfg.AuthorizationEndpoint); endpoint != "" {
 		metadata.AuthorizationEndpoint = endpoint
@@ -195,6 +257,12 @@ func resolveAuthorizationServer(ctx context.Context, client *http.Client, baseUR
 	if endpoint := strings.TrimSpace(cfg.RegistrationEndpoint); endpoint != "" {
 		metadata.RegistrationEndpoint = endpoint
 	}
+	if protectedResourceDiscovery {
+		metadata.protectedResourceURL = strings.TrimSpace(baseURL)
+		metadata.protectAuthorizationEndpoint = strings.TrimSpace(cfg.AuthorizationEndpoint) == ""
+		metadata.protectTokenEndpoint = strings.TrimSpace(cfg.TokenEndpoint) == ""
+		metadata.protectRegistrationEndpoint = strings.TrimSpace(cfg.RegistrationEndpoint) == ""
+	}
 
 	if strings.TrimSpace(metadata.AuthorizationEndpoint) == "" {
 		return authServerMetadata{}, errors.New("no authorization endpoint discovered or configured")
@@ -205,6 +273,9 @@ func resolveAuthorizationServer(ctx context.Context, client *http.Client, baseUR
 	if err := validateResolvedEndpoints(metadata); err != nil {
 		return authServerMetadata{}, err
 	}
+	if err := validateProtectedDiscoveredEndpoints(ctx, metadata); err != nil {
+		return authServerMetadata{}, err
+	}
 	return metadata, nil
 }
 
@@ -363,10 +434,25 @@ func Login(ctx context.Context, options LoginOptions) (StoredToken, error) {
 	}
 	defer listener.Close()
 	redirectURI := fmt.Sprintf("http://%s/callback", listener.Addr().String())
+	protectedEndpointClient := httpClient
+	if metadata.protectRegistrationEndpoint || metadata.protectTokenEndpoint {
+		protectedEndpointClient, err = newAdvertisedOAuthDiscoveryClient(httpClient, metadata.protectedResourceURL)
+		if err != nil {
+			return StoredToken{}, err
+		}
+	}
+	tokenClient := httpClient
+	if metadata.protectTokenEndpoint {
+		tokenClient = protectedEndpointClient
+	}
 
 	if strings.TrimSpace(cfg.ClientID) == "" {
 		if registration := strings.TrimSpace(metadata.RegistrationEndpoint); registration != "" {
-			clientID, clientSecret, regErr := registerClient(loginCtx, httpClient, registration, redirectURI, cfg.Scopes)
+			registrationClient := httpClient
+			if metadata.protectRegistrationEndpoint {
+				registrationClient = protectedEndpointClient
+			}
+			clientID, clientSecret, regErr := registerClient(loginCtx, registrationClient, registration, redirectURI, cfg.Scopes)
 			if regErr != nil {
 				return StoredToken{}, regErr
 			}
@@ -390,7 +476,7 @@ func Login(ctx context.Context, options LoginOptions) (StoredToken, error) {
 	}
 
 	flow := &authorizationFlow{
-		httpClient: httpClient,
+		httpClient: tokenClient,
 		metadata:   metadata,
 		config:     cfg,
 		pkce:       pkce,

internal/mcp/oauth_discovery_network.go

@@ -0,0 +1,290 @@
+package mcp
+
+import (
+	"context"
+	"crypto/tls"
+	"errors"
+	"fmt"
+	"net"
+	"net/http"
+	"net/netip"
+	"net/url"
+	"strings"
+)
+
+var errUnsafeOAuthDiscoveryTarget = errors.New("mcp oauth: refused non-public server-advertised discovery target")
+
+var nonPublicOAuthDiscoveryPrefixes = []netip.Prefix{
+	netip.MustParsePrefix("0.0.0.0/8"),
+	netip.MustParsePrefix("10.0.0.0/8"),
+	netip.MustParsePrefix("100.64.0.0/10"),
+	netip.MustParsePrefix("127.0.0.0/8"),
+	netip.MustParsePrefix("169.254.0.0/16"),
+	netip.MustParsePrefix("172.16.0.0/12"),
+	netip.MustParsePrefix("192.0.0.0/24"),
+	netip.MustParsePrefix("192.0.2.0/24"),
+	netip.MustParsePrefix("192.88.99.0/24"),
+	netip.MustParsePrefix("192.168.0.0/16"),
+	netip.MustParsePrefix("198.18.0.0/15"),
+	netip.MustParsePrefix("198.51.100.0/24"),
+	netip.MustParsePrefix("203.0.113.0/24"),
+	netip.MustParsePrefix("224.0.0.0/4"),
+	netip.MustParsePrefix("240.0.0.0/4"),
+	netip.MustParsePrefix("::/128"),
+	netip.MustParsePrefix("::1/128"),
+	netip.MustParsePrefix("100::/64"),
+	netip.MustParsePrefix("2001:2::/48"),
+	netip.MustParsePrefix("2001:db8::/32"),
+	netip.MustParsePrefix("fc00::/7"),
+	netip.MustParsePrefix("fe80::/10"),
+	netip.MustParsePrefix("ff00::/8"),
+}
+
+type oauthDiscoveryNetworkPolicy struct {
+	allowLoopback bool
+	lookupNetIP   func(context.Context, string, string) ([]netip.Addr, error)
+}
+
+type advertisedOAuthDiscoveryTransport struct {
+	base   http.RoundTripper
+	policy oauthDiscoveryNetworkPolicy
+}
+
+// newAdvertisedOAuthDiscoveryClient binds server-advertised discovery to the
+// public network. Loopback targets remain available only when the operator
+// explicitly configured a loopback MCP resource.
+func newAdvertisedOAuthDiscoveryClient(client *http.Client, resourceURL string) (*http.Client, error) {
+	policy, err := newOAuthDiscoveryNetworkPolicy(resourceURL)
+	if err != nil {
+		return nil, err
+	}
+	copied := withoutDiscoveryRedirects(client)
+	transport := copied.Transport
+	if transport == nil {
+		transport = http.DefaultTransport
+	}
+	copied.Transport = advertisedOAuthDiscoveryTransport{base: transport, policy: policy}
+	return copied, nil
+}
+
+func newOAuthDiscoveryNetworkPolicy(resourceURL string) (oauthDiscoveryNetworkPolicy, error) {
+	parsed, err := url.Parse(strings.TrimSpace(resourceURL))
+	if err != nil || parsed.Hostname() == "" {
+		return oauthDiscoveryNetworkPolicy{}, errors.New("mcp oauth: invalid MCP resource URL for discovery policy")
+	}
+	return oauthDiscoveryNetworkPolicy{allowLoopback: isExplicitOAuthLoopbackHost(parsed.Hostname())}, nil
+}
+
+func validateAdvertisedOAuthDiscoveryURL(resourceURL string, targetURL string) error {
+	policy, err := newOAuthDiscoveryNetworkPolicy(resourceURL)
+	if err != nil {
+		return err
+	}
+	parsed, err := url.Parse(targetURL)
+	if err != nil || parsed.Hostname() == "" {
+		return errUnsafeOAuthDiscoveryTarget
+	}
+	return policy.validateLiteralHost(parsed.Hostname())
+}
+
+func (transport advertisedOAuthDiscoveryTransport) RoundTrip(request *http.Request) (*http.Response, error) {
+	if request == nil || request.URL == nil {
+		return nil, errors.New("mcp oauth: discovery request has no URL")
+	}
+	if err := transport.policy.validateLiteralHost(request.URL.Hostname()); err != nil {
+		return nil, err
+	}
+
+	baseTransport, ok := transport.base.(*http.Transport)
+	if !ok {
+		return nil, errors.New("mcp oauth: cannot enforce discovery network policy with a custom HTTP transport")
+	}
+	addresses, err := transport.policy.resolve(request.Context(), request.URL.Hostname())
+	if err != nil {
+		return nil, err
+	}
+	var lastErr error
+	for index, address := range addresses {
+		attempt := request
+		if index > 0 && request.Body != nil {
+			if request.GetBody == nil {
+				break
+			}
+			body, bodyErr := request.GetBody()
+			if bodyErr != nil {
+				return nil, bodyErr
+			}
+			attempt = request.Clone(request.Context())
+			attempt.Body = body
+		}
+		response, roundTripErr := roundTripPinnedOAuthDiscovery(attempt, baseTransport, address)
+		if roundTripErr == nil {
+			return response, nil
+		}
+		lastErr = roundTripErr
+	}
+	if lastErr == nil {
+		lastErr = errUnsafeOAuthDiscoveryTarget
+	}
+	return nil, lastErr
+}
+
+func roundTripPinnedOAuthDiscovery(request *http.Request, base *http.Transport, address netip.Addr) (*http.Response, error) {
+	pinnedRequest := request.Clone(request.Context())
+	pinnedURL := *request.URL
+	originalHost := request.URL.Hostname()
+	port := request.URL.Port()
+	if port == "" {
+		switch strings.ToLower(request.URL.Scheme) {
+		case "http":
+			port = "80"
+		case "https":
+			port = "443"
+		default:
+			return nil, errUnsafeOAuthDiscoveryTarget
+		}
+	}
+	pinnedURL.Host = net.JoinHostPort(address.String(), port)
+	pinnedRequest.URL = &pinnedURL
+	if pinnedRequest.Host == "" {
+		pinnedRequest.Host = request.URL.Host
+	}
+
+	pinnedTransport := base.Clone()
+	pinnedTransport.DisableKeepAlives = true
+	var proxyURL *url.URL
+	if base.Proxy != nil {
+		var err error
+		proxyURL, err = base.Proxy(request)
+		if err != nil {
+			return nil, fmt.Errorf("mcp oauth: resolve discovery proxy: %w", err)
+		}
+		if proxyURL == nil {
+			pinnedTransport.Proxy = nil
+		} else {
+			pinnedTransport.Proxy = http.ProxyURL(proxyURL)
+		}
+	}
+	if pinnedTransport.TLSClientConfig == nil {
+		pinnedTransport.TLSClientConfig = &tls.Config{ServerName: originalHost} //nolint:gosec // standard verification remains enabled
+	} else {
+		pinnedTransport.TLSClientConfig = pinnedTransport.TLSClientConfig.Clone()
+		pinnedTransport.TLSClientConfig.ServerName = originalHost
+	}
+	// A custom TLS dialer must not resolve the advertised hostname again after
+	// the policy has pinned it. For an HTTPS proxy, however, that proxy remains
+	// the TLS first hop and the transport sends CONNECT to the pinned target.
+	dialContext := pinnedTransport.DialContext
+	if dialContext == nil {
+		dialContext = (&net.Dialer{}).DialContext
+	}
+	pinnedAddress := net.JoinHostPort(address.String(), port)
+	targetTLSConfig := pinnedTransport.TLSClientConfig
+	pinnedTransport.DialTLSContext = func(ctx context.Context, network string, address string) (net.Conn, error) {
+		if proxyURL != nil && strings.EqualFold(proxyURL.Scheme, "https") {
+			proxyTLSConfig := targetTLSConfig.Clone()
+			proxyTLSConfig.ServerName = proxyURL.Hostname()
+			return dialOAuthDiscoveryTLS(ctx, dialContext, network, address, proxyTLSConfig)
+		}
+		return dialOAuthDiscoveryTLS(ctx, dialContext, network, pinnedAddress, targetTLSConfig)
+	}
+	return pinnedTransport.RoundTrip(pinnedRequest)
+}
+
+func dialOAuthDiscoveryTLS(ctx context.Context, dialContext func(context.Context, string, string) (net.Conn, error), network string, address string, config *tls.Config) (net.Conn, error) {
+	connection, err := dialContext(ctx, network, address)
+	if err != nil {
+		return nil, err
+	}
+	tlsConnection := tls.Client(connection, config)
+	if err := tlsConnection.HandshakeContext(ctx); err != nil {
+		connection.Close()
+		return nil, err
+	}
+	return tlsConnection, nil
+}
+
+func (policy oauthDiscoveryNetworkPolicy) resolve(ctx context.Context, host string) ([]netip.Addr, error) {
+	if address, err := netip.ParseAddr(strings.Trim(host, "[]")); err == nil {
+		address = address.Unmap()
+		if err := policy.validateAddress(address); err != nil {
+			return nil, err
+		}
+		return []netip.Addr{address}, nil
+	}
+
+	lookupNetIP := policy.lookupNetIP
+	if lookupNetIP == nil {
+		lookupNetIP = net.DefaultResolver.LookupNetIP
+	}
+	addresses, err := lookupNetIP(ctx, "ip", host)
+	if err != nil {
+		return nil, errors.New("mcp oauth: resolve server-advertised discovery target failed")
+	}
+	if len(addresses) == 0 {
+		return nil, errors.New("mcp oauth: server-advertised discovery target resolved to no addresses")
+	}
+	explicitLoopback := isExplicitOAuthLoopbackHost(host)
+	resolved := make([]netip.Addr, 0, len(addresses))
+	for _, address := range addresses {
+		address = address.Unmap()
+		if explicitLoopback && !address.IsLoopback() {
+			return nil, errUnsafeOAuthDiscoveryTarget
+		}
+		if err := policy.validateAddress(address); err != nil {
+			return nil, err
+		}
+		resolved = append(resolved, address)
+	}
+	return resolved, nil
+}
+
+func (policy oauthDiscoveryNetworkPolicy) validateLiteralHost(host string) error {
+	normalized := strings.ToLower(strings.TrimSuffix(strings.Trim(host, "[]"), "."))
+	if normalized == "" {
+		return errUnsafeOAuthDiscoveryTarget
+	}
+	if isCloudMetadataHostname(normalized) {
+		return errUnsafeOAuthDiscoveryTarget
+	}
+	if isExplicitOAuthLoopbackHost(normalized) && !policy.allowLoopback {
+		return errUnsafeOAuthDiscoveryTarget
+	}
+	if address, err := netip.ParseAddr(normalized); err == nil {
+		return policy.validateAddress(address.Unmap())
+	}
+	return nil
+}
+
+func (policy oauthDiscoveryNetworkPolicy) validateAddress(address netip.Addr) error {
+	if policy.allowLoopback && address.IsLoopback() {
+		return nil
+	}
+	if !address.IsValid() || !address.IsGlobalUnicast() || address.IsPrivate() {
+		return errUnsafeOAuthDiscoveryTarget
+	}
+	for _, prefix := range nonPublicOAuthDiscoveryPrefixes {
+		if prefix.Contains(address) {
+			return errUnsafeOAuthDiscoveryTarget
+		}
+	}
+	return nil
+}
+
+func isExplicitOAuthLoopbackHost(host string) bool {
+	normalized := strings.ToLower(strings.TrimSuffix(strings.Trim(host, "[]"), "."))
+	if normalized == "localhost" || strings.HasSuffix(normalized, ".localhost") {
+		return true
+	}
+	address, err := netip.ParseAddr(normalized)
+	return err == nil && address.Unmap().IsLoopback()
+}
+
+func isCloudMetadataHostname(host string) bool {
+	switch strings.ToLower(strings.TrimSuffix(host, ".")) {
+	case "metadata", "metadata.google.internal", "metadata.azure.internal":
+		return true
+	default:
+		return false
+	}
+}

internal/mcp/oauth_discovery_network_test.go

@@ -0,0 +1,180 @@
+package mcp
+
+import (
+	"bufio"
+	"context"
+	"errors"
+	"io"
+	"net"
+	"net/http"
+	"net/netip"
+	"net/url"
+	"strings"
+	"sync/atomic"
+	"testing"
+)
+
+func TestOAuthDiscoveryNetworkPolicyRejectsNonPublicAddresses(t *testing.T) {
+	policy := oauthDiscoveryNetworkPolicy{}
+	for _, value := range []string{
+		"127.0.0.1",
+		"10.0.0.1",
+		"169.254.169.254",
+		"192.0.2.10",
+		"224.0.0.1",
+		"::1",
+		"fc00::1",
+		"fe80::1",
+		"2001:db8::1",
+	} {
+		t.Run(value, func(t *testing.T) {
+			if err := policy.validateAddress(netip.MustParseAddr(value)); err == nil {
+				t.Fatalf("address %s should be rejected", value)
+			}
+		})
+	}
+	for _, value := range []string{"8.8.8.8", "2606:4700:4700::1111"} {
+		if err := policy.validateAddress(netip.MustParseAddr(value)); err != nil {
+			t.Fatalf("public address %s rejected: %v", value, err)
+		}
+	}
+	loopbackPolicy := oauthDiscoveryNetworkPolicy{allowLoopback: true}
+	if err := loopbackPolicy.validateAddress(netip.MustParseAddr("127.0.0.1")); err != nil {
+		t.Fatalf("explicit loopback resource should allow loopback discovery: %v", err)
+	}
+	if err := loopbackPolicy.validateAddress(netip.MustParseAddr("10.0.0.1")); err == nil {
+		t.Fatal("loopback development must not permit arbitrary private targets")
+	}
+}
+
+func TestProtectedDiscoveryRejectsNonPublicOAuthEndpoints(t *testing.T) {
+	for _, endpoint := range []struct {
+		name     string
+		metadata authServerMetadata
+	}{
+		{
+			name: "authorization",
+			metadata: authServerMetadata{
+				AuthorizationEndpoint:        "http://127.0.0.1/authorize",
+				protectAuthorizationEndpoint: true,
+			},
+		},
+		{
+			name: "token",
+			metadata: authServerMetadata{
+				TokenEndpoint:        "https://10.0.0.1/token",
+				protectTokenEndpoint: true,
+			},
+		},
+		{
+			name: "registration",
+			metadata: authServerMetadata{
+				RegistrationEndpoint:        "https://169.254.169.254/register",
+				protectRegistrationEndpoint: true,
+			},
+		},
+	} {
+		t.Run(endpoint.name, func(t *testing.T) {
+			endpoint.metadata.protectedResourceURL = "https://mcp.example/mcp"
+			if err := validateProtectedDiscoveredEndpoints(context.Background(), endpoint.metadata); err == nil {
+				t.Fatalf("protected %s endpoint should be rejected", endpoint.name)
+			}
+		})
+	}
+}
+
+func TestAdvertisedOAuthDiscoveryRejectsHostnameResolvingPrivateAtUseTime(t *testing.T) {
+	var dialed atomic.Bool
+	policy := oauthDiscoveryNetworkPolicy{
+		lookupNetIP: func(context.Context, string, string) ([]netip.Addr, error) {
+			return []netip.Addr{netip.MustParseAddr("10.0.0.12")}, nil
+		},
+	}
+	client := &http.Client{Transport: advertisedOAuthDiscoveryTransport{
+		base: &http.Transport{DialContext: func(context.Context, string, string) (net.Conn, error) {
+			dialed.Store(true)
+			return nil, io.EOF
+		}},
+		policy: policy,
+	}}
+
+	_, err := client.Get("https://auth.example/.well-known/oauth-authorization-server")
+	if err == nil || !strings.Contains(err.Error(), errUnsafeOAuthDiscoveryTarget.Error()) {
+		t.Fatalf("error = %v, want private-resolution rejection", err)
+	}
+	if dialed.Load() {
+		t.Fatal("private resolved address reached the dialer")
+	}
+}
+
+func TestAdvertisedOAuthDiscoveryPinsResolvedAddress(t *testing.T) {
+	const publicAddress = "93.184.216.34"
+	var dialedAddress string
+	policy := oauthDiscoveryNetworkPolicy{
+		lookupNetIP: func(context.Context, string, string) ([]netip.Addr, error) {
+			return []netip.Addr{netip.MustParseAddr(publicAddress)}, nil
+		},
+	}
+	baseTransport := &http.Transport{DialContext: func(_ context.Context, _, address string) (net.Conn, error) {
+		dialedAddress = address
+		clientConn, serverConn := net.Pipe()
+		go func() {
+			defer serverConn.Close()
+			reader := bufio.NewReader(serverConn)
+			for {
+				line, err := reader.ReadString('\n')
+				if err != nil || line == "\r\n" {
+					break
+				}
+			}
+			_, _ = io.WriteString(serverConn, "HTTP/1.1 200 OK\r\nContent-Length: 2\r\nConnection: close\r\n\r\n{}")
+		}()
+		return clientConn, nil
+	}}
+	client := &http.Client{Transport: advertisedOAuthDiscoveryTransport{base: baseTransport, policy: policy}}
+
+	response, err := client.Get("http://auth.example/metadata")
+	if err != nil {
+		t.Fatalf("GET pinned discovery target: %v", err)
+	}
+	response.Body.Close()
+	if dialedAddress != net.JoinHostPort(publicAddress, "80") {
+		t.Fatalf("dialed %q, want resolved address", dialedAddress)
+	}
+}
+
+func TestPinnedOAuthDiscoveryPreservesHTTPSProxyFirstHop(t *testing.T) {
+	for _, test := range []struct {
+		name     string
+		proxy    string
+		firstHop string
+	}{
+		{name: "HTTP", proxy: "http://proxy.example:8080", firstHop: "proxy.example:8080"},
+		{name: "HTTPS", proxy: "https://proxy.example:8443", firstHop: "proxy.example:8443"},
+		{name: "SOCKS", proxy: "socks5://proxy.example:1080", firstHop: "proxy.example:1080"},
+	} {
+		t.Run(test.name, func(t *testing.T) {
+			proxyURL, err := url.Parse(test.proxy)
+			if err != nil {
+				t.Fatalf("parse proxy URL: %v", err)
+			}
+			var dialedAddress string
+			baseTransport := &http.Transport{
+				Proxy: http.ProxyURL(proxyURL),
+				DialContext: func(_ context.Context, _, address string) (net.Conn, error) {
+					dialedAddress = address
+					return nil, errors.New("stop after observing first hop")
+				},
+			}
+			request, err := http.NewRequestWithContext(context.Background(), http.MethodGet, "https://auth.example/metadata", nil)
+			if err != nil {
+				t.Fatalf("create request: %v", err)
+			}
+
+			_, _ = roundTripPinnedOAuthDiscovery(request, baseTransport, netip.MustParseAddr("93.184.216.34"))
+			if dialedAddress != test.firstHop {
+				t.Fatalf("dialed %q, want %s proxy first hop", dialedAddress, test.name)
+			}
+		})
+	}
+}

internal/mcp/oauth_protected_resource.go

@@ -0,0 +1,233 @@
+package mcp
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"io"
+	"net/http"
+	"net/url"
+	"strings"
+
+	"github.com/Gitlawb/zero/internal/oauth"
+)
+
+const protectedResourceMetadataLimit = 1 << 20
+
+type protectedResourceMetadata struct {
+	Resource             string   `json:"resource"`
+	AuthorizationServers []string `json:"authorization_servers"`
+}
+
+// withoutDiscoveryRedirects returns a shallow client copy that exposes 3xx
+// responses to the caller. Every discovered URL is validated before use, so a
+// redirect must never replace that validated target with an unchecked one.
+func withoutDiscoveryRedirects(client *http.Client) *http.Client {
+	if client == nil {
+		client = http.DefaultClient
+	}
+	copied := *client
+	// Discovery requests are deliberately unauthenticated. A caller-supplied
+	// jar must not turn a plain metadata GET into a credential-bearing request.
+	copied.Jar = nil
+	copied.CheckRedirect = func(*http.Request, []*http.Request) error {
+		return http.ErrUseLastResponse
+	}
+	return &copied
+}
+
+// discoverProtectedResourceAuthorizationServer follows the RFC 9728 URL
+// advertised by a protected MCP resource. found is false when the endpoint does
+// not advertise protected-resource metadata, allowing legacy direct discovery.
+func discoverProtectedResourceAuthorizationServer(ctx context.Context, client *http.Client, resourceURL string) (issuer string, found bool, err error) {
+	resourceURL = strings.TrimSpace(resourceURL)
+	client = withoutDiscoveryRedirects(client)
+	metadataURL, found, err := probeProtectedResourceMetadataURL(ctx, client, resourceURL)
+	if err != nil || !found {
+		return "", found, err
+	}
+	if err := validateResourceMetadataOrigin(resourceURL, metadataURL); err != nil {
+		return "", true, err
+	}
+	client, err = newAdvertisedOAuthDiscoveryClient(client, resourceURL)
+	if err != nil {
+		return "", true, err
+	}
+	metadata, err := fetchProtectedResourceMetadata(ctx, client, metadataURL)
+	if err != nil {
+		return "", true, err
+	}
+	if metadata.Resource != resourceURL {
+		return "", true, errors.New("mcp oauth: protected resource metadata resource does not match the MCP server URL")
+	}
+	if len(metadata.AuthorizationServers) == 0 {
+		return "", true, errors.New("mcp oauth: protected resource metadata has no authorization_servers")
+	}
+	issuer = metadata.AuthorizationServers[0]
+	if strings.TrimSpace(issuer) == "" {
+		return "", true, errors.New("mcp oauth: protected resource metadata has an empty authorization server")
+	}
+	if issuer != strings.TrimSpace(issuer) {
+		return "", true, errors.New("mcp oauth: protected resource authorization server must not contain surrounding whitespace")
+	}
+	if err := oauth.ValidateEndpointURL(issuer); err != nil {
+		return "", true, fmt.Errorf("mcp oauth: protected resource authorization server: %w", err)
+	}
+	if err := validateAdvertisedOAuthDiscoveryURL(resourceURL, issuer); err != nil {
+		return "", true, err
+	}
+	return issuer, true, nil
+}
+
+func validateResourceMetadataOrigin(resourceURL string, metadataURL string) error {
+	resource, resourceErr := url.Parse(resourceURL)
+	metadata, metadataErr := url.Parse(metadataURL)
+	if resourceErr != nil || metadataErr != nil || !sameMCPOrigin(resource, metadata) {
+		return errors.New("mcp oauth: protected resource metadata URL must be same-origin with the MCP server URL")
+	}
+	return nil
+}
+
+func probeProtectedResourceMetadataURL(ctx context.Context, client *http.Client, resourceURL string) (string, bool, error) {
+	if client == nil {
+		client = http.DefaultClient
+	}
+	request, err := http.NewRequestWithContext(ctx, http.MethodGet, strings.TrimSpace(resourceURL), nil)
+	if err != nil {
+		return "", false, errors.New("mcp oauth: invalid MCP resource URL")
+	}
+	request.Header.Set("Accept", "application/json, text/event-stream")
+	request.Header.Set("MCP-Protocol-Version", defaultProtocolVersion)
+	response, err := client.Do(request)
+	if err != nil {
+		// A resource that cannot be probed may still support the legacy direct
+		// authorization-server discovery flow.
+		return "", false, nil
+	}
+	defer response.Body.Close()
+	if response.StatusCode != http.StatusUnauthorized {
+		return "", false, nil
+	}
+	metadataURL, found, err := parseResourceMetadataURL(response.Header.Values("WWW-Authenticate"))
+	if err != nil {
+		return "", false, fmt.Errorf("mcp oauth: invalid WWW-Authenticate resource_metadata parameter: %w", err)
+	}
+	if !found {
+		return "", false, nil
+	}
+	if err := oauth.ValidateEndpointURL(metadataURL); err != nil {
+		return "", false, fmt.Errorf("mcp oauth: protected resource metadata URL: %w", err)
+	}
+	return metadataURL, true, nil
+}
+
+func fetchProtectedResourceMetadata(ctx context.Context, client *http.Client, metadataURL string) (protectedResourceMetadata, error) {
+	if client == nil {
+		client = http.DefaultClient
+	}
+	request, err := http.NewRequestWithContext(ctx, http.MethodGet, metadataURL, nil)
+	if err != nil {
+		return protectedResourceMetadata{}, errors.New("mcp oauth: invalid protected resource metadata URL")
+	}
+	request.Header.Set("Accept", "application/json")
+	response, err := client.Do(request)
+	if err != nil {
+		return protectedResourceMetadata{}, errors.New("mcp oauth: fetch protected resource metadata failed")
+	}
+	defer response.Body.Close()
+	if response.StatusCode < http.StatusOK || response.StatusCode >= http.StatusMultipleChoices {
+		return protectedResourceMetadata{}, fmt.Errorf("mcp oauth: protected resource metadata returned HTTP %d", response.StatusCode)
+	}
+	var metadata protectedResourceMetadata
+	if err := json.NewDecoder(io.LimitReader(response.Body, protectedResourceMetadataLimit)).Decode(&metadata); err != nil {
+		return protectedResourceMetadata{}, errors.New("mcp oauth: decode protected resource metadata failed")
+	}
+	return metadata, nil
+}
+
+func parseResourceMetadataURL(headerValues []string) (string, bool, error) {
+	var selected string
+	for _, headerValue := range headerValues {
+		for index := 0; index < len(headerValue); {
+			if headerValue[index] == '"' {
+				_, next, err := readAuthQuotedString(headerValue, index)
+				if err != nil {
+					// Malformed parameters for another authentication scheme do
+					// not suppress a valid challenge in a separate header value.
+					break
+				}
+				index = next
+				continue
+			}
+			if !isAuthTokenByte(headerValue[index]) {
+				index++
+				continue
+			}
+			start := index
+			for index < len(headerValue) && isAuthTokenByte(headerValue[index]) {
+				index++
+			}
+			name := headerValue[start:index]
+			for index < len(headerValue) && (headerValue[index] == ' ' || headerValue[index] == '\t') {
+				index++
+			}
+			if index >= len(headerValue) || headerValue[index] != '=' {
+				continue
+			}
+			index++
+			for index < len(headerValue) && (headerValue[index] == ' ' || headerValue[index] == '\t') {
+				index++
+			}
+			if !strings.EqualFold(name, "resource_metadata") {
+				continue
+			}
+			if index >= len(headerValue) || headerValue[index] != '"' {
+				return "", false, errors.New("resource_metadata must be a quoted URL")
+			}
+			value, next, err := readAuthQuotedString(headerValue, index)
+			if err != nil {
+				return "", false, err
+			}
+			value = strings.TrimSpace(value)
+			if value == "" {
+				return "", false, errors.New("resource_metadata URL is empty")
+			}
+			if selected != "" && selected != value {
+				return "", false, errors.New("conflicting resource_metadata URLs")
+			}
+			selected = value
+			index = next
+		}
+	}
+	return selected, selected != "", nil
+}
+
+func readAuthQuotedString(value string, quote int) (string, int, error) {
+	var decoded strings.Builder
+	for index := quote + 1; index < len(value); index++ {
+		switch value[index] {
+		case '"':
+			return decoded.String(), index + 1, nil
+		case '\\':
+			index++
+			if index >= len(value) {
+				return "", 0, errors.New("unterminated quoted resource_metadata URL")
+			}
+			decoded.WriteByte(value[index])
+		default:
+			if value[index] < 0x20 || value[index] == 0x7f {
+				return "", 0, errors.New("resource_metadata URL contains a control character")
+			}
+			decoded.WriteByte(value[index])
+		}
+	}
+	return "", 0, errors.New("unterminated quoted resource_metadata URL")
+}
+
+func isAuthTokenByte(value byte) bool {
+	if value >= 'a' && value <= 'z' || value >= 'A' && value <= 'Z' || value >= '0' && value <= '9' {
+		return true
+	}
+	return strings.ContainsRune("!#$%&'*+-.^_`|~", rune(value))
+}

internal/mcp/oauth_protected_resource_test.go

@@ -0,0 +1,742 @@
+package mcp
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"io"
+	"net"
+	"net/http"
+	"net/http/cookiejar"
+	"net/http/httptest"
+	"net/url"
+	"strings"
+	"sync/atomic"
+	"testing"
+	"time"
+)
+
+func TestParseResourceMetadataURL(t *testing.T) {
+	got, found, err := parseResourceMetadataURL([]string{
+		`Basic realm="resource_metadata=not-a-parameter"`,
+		`Bearer realm="OAuth", scope="read", Resource_Metadata="https://mcp.example/resource-metadata"`,
+	})
+	if err != nil || !found {
+		t.Fatalf("parseResourceMetadataURL() found=%v err=%v", found, err)
+	}
+	if got != "https://mcp.example/resource-metadata" {
+		t.Fatalf("resource metadata URL = %q", got)
+	}
+
+	got, found, err = parseResourceMetadataURL([]string{
+		`Basic realm="unterminated`,
+		`Bearer resource_metadata="https://mcp.example/fallback-metadata"`,
+	})
+	if err != nil || !found || got != "https://mcp.example/fallback-metadata" {
+		t.Fatalf("unrelated malformed challenge blocked discovery: got=%q found=%v err=%v", got, found, err)
+	}
+
+	for name, headers := range map[string][]string{
+		"unquoted":     {`Bearer resource_metadata=https://mcp.example/metadata`},
+		"unterminated": {`Bearer resource_metadata="https://mcp.example/metadata`},
+		"conflicting": {
+			`Bearer resource_metadata="https://mcp.example/one"`,
+			`DPoP resource_metadata="https://mcp.example/two"`,
+		},
+	} {
+		t.Run(name, func(t *testing.T) {
+			if _, _, err := parseResourceMetadataURL(headers); err == nil {
+				t.Fatal("expected malformed resource_metadata rejection")
+			}
+		})
+	}
+}
+
+func TestProtectedResourceDiscoveryRejectsInvalidMetadata(t *testing.T) {
+	for _, test := range []struct {
+		name      string
+		challenge func(base string) string
+		metadata  func(base string) string
+		wantError string
+	}{
+		{
+			name:      "malformed challenge",
+			challenge: func(string) string { return `Bearer resource_metadata="unterminated` },
+			wantError: "WWW-Authenticate",
+		},
+		{
+			name:      "insecure metadata URL",
+			challenge: func(string) string { return `Bearer resource_metadata="http://metadata.example/resource"` },
+			wantError: "metadata URL",
+		},
+		{
+			name:      "invalid JSON",
+			challenge: func(base string) string { return `Bearer resource_metadata="` + base + `/metadata"` },
+			metadata:  func(string) string { return `{` },
+			wantError: "decode protected resource metadata",
+		},
+		{
+			name:      "resource mismatch",
+			challenge: func(base string) string { return `Bearer resource_metadata="` + base + `/metadata"` },
+			metadata: func(base string) string {
+				return `{"resource":"` + base + `/other","authorization_servers":["https://auth.example"]}`
+			},
+			wantError: "does not match",
+		},
+		{
+			name:      "resource leading whitespace mismatch",
+			challenge: func(base string) string { return `Bearer resource_metadata="` + base + `/metadata"` },
+			metadata: func(base string) string {
+				return `{"resource":" ` + base + `/mcp","authorization_servers":["https://auth.example"]}`
+			},
+			wantError: "does not match",
+		},
+		{
+			name:      "resource trailing whitespace mismatch",
+			challenge: func(base string) string { return `Bearer resource_metadata="` + base + `/metadata"` },
+			metadata: func(base string) string {
+				return `{"resource":"` + base + `/mcp ","authorization_servers":["https://auth.example"]}`
+			},
+			wantError: "does not match",
+		},
+		{
+			name:      "authorization servers missing",
+			challenge: func(base string) string { return `Bearer resource_metadata="` + base + `/metadata"` },
+			metadata: func(base string) string {
+				return `{"resource":"` + base + `/mcp"}`
+			},
+			wantError: "authorization_servers",
+		},
+		{
+			name:      "insecure authorization server",
+			challenge: func(base string) string { return `Bearer resource_metadata="` + base + `/metadata"` },
+			metadata: func(base string) string {
+				return `{"resource":"` + base + `/mcp","authorization_servers":["http://auth.example"]}`
+			},
+			wantError: "authorization server",
+		},
+	} {
+		t.Run(test.name, func(t *testing.T) {
+			server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+				base := "http://" + r.Host
+				switch r.URL.Path {
+				case "/mcp":
+					w.Header().Set("WWW-Authenticate", test.challenge(base))
+					w.WriteHeader(http.StatusUnauthorized)
+				case "/metadata":
+					if test.metadata == nil {
+						http.NotFound(w, r)
+						return
+					}
+					_, _ = w.Write([]byte(test.metadata(base)))
+				default:
+					http.NotFound(w, r)
+				}
+			}))
+			defer server.Close()
+
+			_, _, err := discoverProtectedResourceAuthorizationServer(context.Background(), server.Client(), server.URL+"/mcp")
+			if err == nil || !strings.Contains(err.Error(), test.wantError) {
+				t.Fatalf("error = %v, want %q", err, test.wantError)
+			}
+		})
+	}
+}
+
+func TestProtectedResourceProbeSendsNoCredentials(t *testing.T) {
+	var authorization, cookie string
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		authorization = r.Header.Get("Authorization")
+		cookie = r.Header.Get("Cookie")
+		w.WriteHeader(http.StatusNotFound)
+	}))
+	defer server.Close()
+	jar, err := cookiejar.New(nil)
+	if err != nil {
+		t.Fatalf("create cookie jar: %v", err)
+	}
+	serverURL, err := url.Parse(server.URL)
+	if err != nil {
+		t.Fatalf("parse server URL: %v", err)
+	}
+	jar.SetCookies(serverURL, []*http.Cookie{{Name: "session", Value: "secret"}})
+	client := server.Client()
+	client.Jar = jar
+
+	_, found, err := discoverProtectedResourceAuthorizationServer(context.Background(), client, server.URL+"/mcp")
+	if err != nil || found {
+		t.Fatalf("discovery found=%v err=%v", found, err)
+	}
+	if authorization != "" || cookie != "" {
+		t.Fatalf("probe sent credentials: authorization=%q cookie=%q", authorization, cookie)
+	}
+}
+
+func TestDirectAuthorizationServerDiscoverySendsNoCookies(t *testing.T) {
+	var cookie string
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		cookie = r.Header.Get("Cookie")
+		base := "http://" + r.Host
+		_ = json.NewEncoder(w).Encode(map[string]any{
+			"issuer":                 base,
+			"authorization_endpoint": base + "/authorize",
+			"token_endpoint":         base + "/token",
+		})
+	}))
+	defer server.Close()
+	jar, err := cookiejar.New(nil)
+	if err != nil {
+		t.Fatalf("create cookie jar: %v", err)
+	}
+	serverURL, err := url.Parse(server.URL)
+	if err != nil {
+		t.Fatalf("parse server URL: %v", err)
+	}
+	jar.SetCookies(serverURL, []*http.Cookie{{Name: "session", Value: "secret"}})
+	client := server.Client()
+	client.Jar = jar
+
+	if _, err := resolveAuthorizationServer(context.Background(), client, server.URL, OAuthConfig{}); err != nil {
+		t.Fatalf("resolveAuthorizationServer() error = %v", err)
+	}
+	if cookie != "" {
+		t.Fatalf("direct discovery sent cookie %q", cookie)
+	}
+}
+
+func TestProtectedResourceDiscoveryRejectsAdvertisedLoopbackMetadata(t *testing.T) {
+	var metadataHits atomic.Int64
+	client := &http.Client{Transport: roundTripperFunc(func(request *http.Request) (*http.Response, error) {
+		response := &http.Response{
+			StatusCode: http.StatusOK,
+			Header:     make(http.Header),
+			Body:       io.NopCloser(strings.NewReader("")),
+			Request:    request,
+		}
+		switch request.URL.String() {
+		case "https://mcp.example/mcp":
+			response.StatusCode = http.StatusUnauthorized
+			response.Header.Set("WWW-Authenticate", `Bearer resource_metadata="http://127.0.0.1/metadata"`)
+		case "http://127.0.0.1/metadata":
+			metadataHits.Add(1)
+			response.Body = io.NopCloser(strings.NewReader(`{"resource":"https://mcp.example/mcp","authorization_servers":["https://auth.example"]}`))
+		default:
+			response.StatusCode = http.StatusNotFound
+		}
+		return response, nil
+	})}
+
+	_, _, err := discoverProtectedResourceAuthorizationServer(context.Background(), client, "https://mcp.example/mcp")
+	if err == nil {
+		t.Fatal("advertised loopback metadata URL should be rejected")
+	}
+	if metadataHits.Load() != 0 {
+		t.Fatalf("loopback metadata target was fetched %d time(s)", metadataHits.Load())
+	}
+}
+
+func TestProtectedResourceDiscoveryRejectsAdvertisedLoopbackIssuer(t *testing.T) {
+	var issuerHits atomic.Int64
+	client := &http.Client{Transport: roundTripperFunc(func(request *http.Request) (*http.Response, error) {
+		response := &http.Response{
+			StatusCode: http.StatusOK,
+			Header:     make(http.Header),
+			Body:       io.NopCloser(strings.NewReader("")),
+			Request:    request,
+		}
+		switch request.URL.String() {
+		case "https://mcp.example/mcp":
+			response.StatusCode = http.StatusUnauthorized
+			response.Header.Set("WWW-Authenticate", `Bearer resource_metadata="https://mcp.example/metadata"`)
+		case "https://mcp.example/metadata":
+			response.Body = io.NopCloser(strings.NewReader(`{"resource":"https://mcp.example/mcp","authorization_servers":["http://127.0.0.1"]}`))
+		case "http://127.0.0.1/.well-known/oauth-authorization-server":
+			issuerHits.Add(1)
+			response.Body = io.NopCloser(strings.NewReader(`{"issuer":"http://127.0.0.1","authorization_endpoint":"http://127.0.0.1/authorize","token_endpoint":"http://127.0.0.1/token"}`))
+		default:
+			response.StatusCode = http.StatusNotFound
+		}
+		return response, nil
+	})}
+
+	_, err := resolveAuthorizationServer(context.Background(), client, "https://mcp.example/mcp", OAuthConfig{})
+	if err == nil {
+		t.Fatal("advertised loopback issuer should be rejected")
+	}
+	if issuerHits.Load() != 0 {
+		t.Fatalf("loopback issuer target was fetched %d time(s)", issuerHits.Load())
+	}
+}
+
+func TestProtectedResourceDiscoveryRejectsAdvertisedPrivateTargets(t *testing.T) {
+	for _, target := range []string{
+		"http://10.0.0.8/metadata",
+		"https://169.254.169.254/metadata",
+		"https://metadata.google.internal/metadata",
+	} {
+		t.Run(target, func(t *testing.T) {
+			if err := validateAdvertisedOAuthDiscoveryURL("https://mcp.example/mcp", target); err == nil {
+				t.Fatalf("advertised target %q should be rejected", target)
+			}
+		})
+	}
+}
+
+func TestProtectedDiscoveryPathsSendNoCookies(t *testing.T) {
+	var probeCookie, resourceCookie, issuerCookie string
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		base := "http://" + r.Host
+		switch r.URL.Path {
+		case "/mcp":
+			probeCookie = r.Header.Get("Cookie")
+			w.Header().Set("WWW-Authenticate", `Bearer resource_metadata="`+base+`/metadata"`)
+			w.WriteHeader(http.StatusUnauthorized)
+		case "/metadata":
+			resourceCookie = r.Header.Get("Cookie")
+			_ = json.NewEncoder(w).Encode(map[string]any{
+				"resource":              base + "/mcp",
+				"authorization_servers": []string{base},
+			})
+		case "/.well-known/oauth-authorization-server":
+			issuerCookie = r.Header.Get("Cookie")
+			_ = json.NewEncoder(w).Encode(map[string]any{
+				"issuer":                 base,
+				"authorization_endpoint": base + "/authorize",
+				"token_endpoint":         base + "/token",
+			})
+		default:
+			http.NotFound(w, r)
+		}
+	}))
+	defer server.Close()
+	jar, err := cookiejar.New(nil)
+	if err != nil {
+		t.Fatalf("create cookie jar: %v", err)
+	}
+	serverURL, err := url.Parse(server.URL)
+	if err != nil {
+		t.Fatalf("parse server URL: %v", err)
+	}
+	jar.SetCookies(serverURL, []*http.Cookie{{Name: "session", Value: "secret"}})
+	client := server.Client()
+	client.Jar = jar
+
+	if _, err := resolveAuthorizationServer(context.Background(), client, server.URL+"/mcp", OAuthConfig{}); err != nil {
+		t.Fatalf("resolveAuthorizationServer() error = %v", err)
+	}
+	if probeCookie != "" || resourceCookie != "" || issuerCookie != "" {
+		t.Fatalf("discovery sent cookies: probe=%q resource=%q issuer=%q", probeCookie, resourceCookie, issuerCookie)
+	}
+}
+
+func TestProtectedDiscoveryPreservesExplicitEndpointOverride(t *testing.T) {
+	fixture := newPublicProtectedOAuthFixture(t, "", "https://93.184.216.35/token", "", "")
+	explicitToken := "http://127.0.0.1:19432/token"
+	metadata, err := resolveAuthorizationServer(context.Background(), fixture.client, fixture.resourceURL, OAuthConfig{TokenEndpoint: explicitToken})
+	if err != nil {
+		t.Fatalf("resolve with explicit endpoint override: %v", err)
+	}
+	if metadata.TokenEndpoint != explicitToken || metadata.protectTokenEndpoint {
+		t.Fatalf("explicit token override lost provenance: endpoint=%q protected=%v", metadata.TokenEndpoint, metadata.protectTokenEndpoint)
+	}
+}
+
+func TestProtectedDiscoveryRejectsLoopbackRegistrationEndpointBeforeUse(t *testing.T) {
+	var registrationHits atomic.Int64
+	registration := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+		registrationHits.Add(1)
+		_ = json.NewEncoder(w).Encode(map[string]any{"client_id": "registered-client"})
+	}))
+	defer registration.Close()
+	fixture := newPublicProtectedOAuthFixture(t, registration.URL+"/register", "https://93.184.216.35/token", "", "")
+
+	_, err := Login(context.Background(), LoginOptions{
+		ServerName: "registration-ssrf",
+		ServerURL:  fixture.resourceURL,
+		HTTPClient: fixture.client,
+		OpenBrowser: func(string) error {
+			return errors.New("authorization browser should not open")
+		},
+		Timeout: 5 * time.Second,
+	})
+	if err == nil {
+		t.Fatal("protected discovery should reject a loopback registration endpoint")
+	}
+	if registrationHits.Load() != 0 {
+		t.Fatalf("loopback registration endpoint received %d request(s)", registrationHits.Load())
+	}
+}
+
+func TestProtectedDiscoveryRejectsLoopbackTokenEndpointBeforeUse(t *testing.T) {
+	var tokenHits atomic.Int64
+	tokenServer := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+		tokenHits.Add(1)
+		_ = json.NewEncoder(w).Encode(map[string]any{
+			"access_token": "unexpected",
+			"token_type":   "Bearer",
+		})
+	}))
+	defer tokenServer.Close()
+	fixture := newPublicProtectedOAuthFixture(t, "", tokenServer.URL+"/token", "", "")
+
+	_, err := Login(context.Background(), LoginOptions{
+		ServerName: "token-ssrf",
+		ServerURL:  fixture.resourceURL,
+		Config:     OAuthConfig{ClientID: "configured-client"},
+		HTTPClient: fixture.client,
+		OpenBrowser: func(authURL string) error {
+			parsed, parseErr := url.Parse(authURL)
+			if parseErr != nil {
+				return parseErr
+			}
+			callbackURL := parsed.Query().Get("redirect_uri") + "?code=code&state=" + url.QueryEscape(parsed.Query().Get("state"))
+			go func() {
+				for attempt := 0; attempt < 20; attempt++ {
+					response, requestErr := http.Get(callbackURL)
+					if requestErr == nil {
+						response.Body.Close()
+						return
+					}
+					time.Sleep(25 * time.Millisecond)
+				}
+			}()
+			return nil
+		},
+		Timeout: 5 * time.Second,
+	})
+	if err == nil {
+		t.Fatal("protected discovery should reject a loopback token endpoint")
+	}
+	if tokenHits.Load() != 0 {
+		t.Fatalf("loopback token endpoint received %d request(s)", tokenHits.Load())
+	}
+}
+
+func TestProtectedDiscoveryRegistrationRefusesPublicToPrivateRedirect(t *testing.T) {
+	var victimHits atomic.Int64
+	victim := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+		victimHits.Add(1)
+		_ = json.NewEncoder(w).Encode(map[string]any{"client_id": "redirected-client"})
+	}))
+	defer victim.Close()
+	fixture := newPublicProtectedOAuthFixture(t, "", "https://93.184.216.35/token", victim.URL+"/register", "")
+
+	_, err := Login(context.Background(), LoginOptions{
+		ServerName: "registration-redirect",
+		ServerURL:  fixture.resourceURL,
+		HTTPClient: fixture.client,
+		OpenBrowser: func(string) error {
+			return errors.New("authorization browser should not open")
+		},
+		Timeout: 5 * time.Second,
+	})
+	if err == nil {
+		t.Fatal("protected registration redirect should be refused")
+	}
+	if victimHits.Load() != 0 {
+		t.Fatalf("registration redirect reached private victim %d time(s)", victimHits.Load())
+	}
+}
+
+func TestProtectedDiscoveryTokenRefusesPublicToPrivateRedirect(t *testing.T) {
+	var victimHits atomic.Int64
+	victim := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+		victimHits.Add(1)
+		_ = json.NewEncoder(w).Encode(map[string]any{"access_token": "redirected-token", "token_type": "Bearer"})
+	}))
+	defer victim.Close()
+	fixture := newPublicProtectedOAuthFixture(t, "", "", "", victim.URL+"/token")
+
+	_, err := Login(context.Background(), LoginOptions{
+		ServerName: "token-redirect",
+		ServerURL:  fixture.resourceURL,
+		Config:     OAuthConfig{ClientID: "configured-client"},
+		HTTPClient: fixture.client,
+		OpenBrowser: func(authURL string) error {
+			parsed, parseErr := url.Parse(authURL)
+			if parseErr != nil {
+				return parseErr
+			}
+			callbackURL := parsed.Query().Get("redirect_uri") + "?code=code&state=" + url.QueryEscape(parsed.Query().Get("state"))
+			go func() {
+				for attempt := 0; attempt < 20; attempt++ {
+					response, requestErr := http.Get(callbackURL)
+					if requestErr == nil {
+						response.Body.Close()
+						return
+					}
+					time.Sleep(25 * time.Millisecond)
+				}
+			}()
+			return nil
+		},
+		Timeout: 5 * time.Second,
+	})
+	if err == nil {
+		t.Fatal("protected token redirect should be refused")
+	}
+	if victimHits.Load() != 0 {
+		t.Fatalf("token redirect reached private victim %d time(s)", victimHits.Load())
+	}
+}
+
+type publicProtectedOAuthFixture struct {
+	client      *http.Client
+	resourceURL string
+}
+
+func newPublicProtectedOAuthFixture(t *testing.T, registrationEndpoint string, tokenEndpoint string, registrationRedirect string, tokenRedirect string) publicProtectedOAuthFixture {
+	t.Helper()
+	var resourceOrigin, issuerOrigin string
+	gateway := httptest.NewTLSServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		resourceHost := strings.TrimPrefix(resourceOrigin, "https://")
+		issuerHost := strings.TrimPrefix(issuerOrigin, "https://")
+		switch {
+		case r.Host == resourceHost && r.URL.Path == "/mcp":
+			w.Header().Set("WWW-Authenticate", `Bearer resource_metadata="`+resourceOrigin+`/metadata"`)
+			w.WriteHeader(http.StatusUnauthorized)
+		case r.Host == resourceHost && r.URL.Path == "/metadata":
+			_ = json.NewEncoder(w).Encode(map[string]any{
+				"resource":              resourceOrigin + "/mcp",
+				"authorization_servers": []string{issuerOrigin},
+			})
+		case r.Host == issuerHost && r.URL.Path == "/.well-known/oauth-authorization-server":
+			metadataRegistration := registrationEndpoint
+			metadataToken := tokenEndpoint
+			if registrationRedirect != "" {
+				metadataRegistration = issuerOrigin + "/register"
+			}
+			if tokenRedirect != "" {
+				metadataToken = issuerOrigin + "/token"
+			}
+			_ = json.NewEncoder(w).Encode(map[string]any{
+				"issuer":                 issuerOrigin,
+				"authorization_endpoint": issuerOrigin + "/authorize",
+				"token_endpoint":         metadataToken,
+				"registration_endpoint":  metadataRegistration,
+			})
+		case r.Host == issuerHost && r.URL.Path == "/register" && registrationRedirect != "":
+			http.Redirect(w, r, registrationRedirect, http.StatusTemporaryRedirect)
+		case r.Host == issuerHost && r.URL.Path == "/token" && tokenRedirect != "":
+			http.Redirect(w, r, tokenRedirect, http.StatusTemporaryRedirect)
+		default:
+			http.NotFound(w, r)
+		}
+	}))
+	t.Cleanup(gateway.Close)
+	port := gateway.Listener.Addr().(*net.TCPAddr).Port
+	resourceOrigin = fmt.Sprintf("https://93.184.216.34:%d", port)
+	issuerOrigin = fmt.Sprintf("https://93.184.216.35:%d", port)
+
+	transport := gateway.Client().Transport.(*http.Transport).Clone()
+	transport.TLSClientConfig = transport.TLSClientConfig.Clone()
+	transport.TLSClientConfig.InsecureSkipVerify = true //nolint:gosec // hermetic public-address routing fixture
+	dialer := &net.Dialer{}
+	gatewayAddress := gateway.Listener.Addr().String()
+	transport.DialContext = func(ctx context.Context, network string, address string) (net.Conn, error) {
+		host, _, err := net.SplitHostPort(address)
+		if err == nil && (host == "93.184.216.34" || host == "93.184.216.35") {
+			return dialer.DialContext(ctx, network, gatewayAddress)
+		}
+		return dialer.DialContext(ctx, network, address)
+	}
+	return publicProtectedOAuthFixture{
+		client:      &http.Client{Transport: transport},
+		resourceURL: resourceOrigin + "/mcp",
+	}
+}
+
+func TestProtectedResourceProbeDoesNotFollowRedirects(t *testing.T) {
+	var redirectedHits atomic.Int64
+	redirected := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+		redirectedHits.Add(1)
+		w.WriteHeader(http.StatusUnauthorized)
+	}))
+	defer redirected.Close()
+	source := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		http.Redirect(w, r, redirected.URL+"/mcp", http.StatusFound)
+	}))
+	defer source.Close()
+
+	_, found, err := discoverProtectedResourceAuthorizationServer(context.Background(), source.Client(), source.URL+"/mcp")
+	if err != nil || found {
+		t.Fatalf("redirected probe found=%v err=%v", found, err)
+	}
+	if redirectedHits.Load() != 0 {
+		t.Fatalf("probe followed redirect %d time(s)", redirectedHits.Load())
+	}
+}
+
+func TestProtectedResourceMetadataDoesNotFollowRedirects(t *testing.T) {
+	var redirectedHits atomic.Int64
+	redirected := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+		redirectedHits.Add(1)
+		_ = json.NewEncoder(w).Encode(map[string]any{
+			"resource":              "https://attacker.example/mcp",
+			"authorization_servers": []string{"https://attacker.example"},
+		})
+	}))
+	defer redirected.Close()
+	source := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		base := "http://" + r.Host
+		switch r.URL.Path {
+		case "/mcp":
+			w.Header().Set("WWW-Authenticate", `Bearer resource_metadata="`+base+`/metadata"`)
+			w.WriteHeader(http.StatusUnauthorized)
+		case "/metadata":
+			http.Redirect(w, r, redirected.URL+"/metadata", http.StatusFound)
+		}
+	}))
+	defer source.Close()
+
+	_, _, err := discoverProtectedResourceAuthorizationServer(context.Background(), source.Client(), source.URL+"/mcp")
+	if err == nil || !strings.Contains(err.Error(), "HTTP 302") {
+		t.Fatalf("error = %v, want redirect refusal", err)
+	}
+	if redirectedHits.Load() != 0 {
+		t.Fatalf("metadata fetch followed redirect %d time(s)", redirectedHits.Load())
+	}
+}
+
+func TestResolveAuthorizationServerRejectsProtectedIssuerMismatch(t *testing.T) {
+	authorizationServer := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		base := "http://" + r.Host
+		_ = json.NewEncoder(w).Encode(map[string]any{
+			"issuer":                 "https://unexpected.example",
+			"authorization_endpoint": base + "/authorize",
+			"token_endpoint":         base + "/token",
+		})
+	}))
+	defer authorizationServer.Close()
+	resourceServer := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		base := "http://" + r.Host
+		switch r.URL.Path {
+		case "/mcp":
+			w.Header().Set("WWW-Authenticate", `Bearer resource_metadata="`+base+`/metadata"`)
+			w.WriteHeader(http.StatusUnauthorized)
+		case "/metadata":
+			_ = json.NewEncoder(w).Encode(map[string]any{
+				"resource":              base + "/mcp",
+				"authorization_servers": []string{authorizationServer.URL},
+			})
+		}
+	}))
+	defer resourceServer.Close()
+
+	_, err := resolveAuthorizationServer(context.Background(), resourceServer.Client(), resourceServer.URL+"/mcp", OAuthConfig{})
+	if err == nil || !strings.Contains(err.Error(), "issuer does not match") {
+		t.Fatalf("error = %v, want issuer mismatch", err)
+	}
+}
+
+func TestResolveAuthorizationServerRejectsMissingProtectedIssuer(t *testing.T) {
+	authorizationServer := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		base := "http://" + r.Host
+		_ = json.NewEncoder(w).Encode(map[string]any{
+			"authorization_endpoint": base + "/authorize",
+			"token_endpoint":         base + "/token",
+		})
+	}))
+	defer authorizationServer.Close()
+	resourceServer := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		base := "http://" + r.Host
+		switch r.URL.Path {
+		case "/mcp":
+			w.Header().Set("WWW-Authenticate", `Bearer resource_metadata="`+base+`/metadata"`)
+			w.WriteHeader(http.StatusUnauthorized)
+		case "/metadata":
+			_ = json.NewEncoder(w).Encode(map[string]any{
+				"resource":              base + "/mcp",
+				"authorization_servers": []string{authorizationServer.URL},
+			})
+		}
+	}))
+	defer resourceServer.Close()
+
+	_, err := resolveAuthorizationServer(context.Background(), resourceServer.Client(), resourceServer.URL+"/mcp", OAuthConfig{})
+	if err == nil || !strings.Contains(err.Error(), "issuer") {
+		t.Fatalf("error = %v, want missing issuer rejection", err)
+	}
+}
+
+func TestResolveAuthorizationServerRejectsWhitespaceAlteredProtectedIssuer(t *testing.T) {
+	for _, alter := range []struct {
+		name  string
+		apply func(string) string
+	}{
+		{name: "leading", apply: func(value string) string { return " " + value }},
+		{name: "trailing", apply: func(value string) string { return value + " " }},
+	} {
+		t.Run(alter.name, func(t *testing.T) {
+			authorizationServer := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+				base := "http://" + r.Host
+				_ = json.NewEncoder(w).Encode(map[string]any{
+					"issuer":                 alter.apply(base),
+					"authorization_endpoint": base + "/authorize",
+					"token_endpoint":         base + "/token",
+				})
+			}))
+			defer authorizationServer.Close()
+			resourceServer := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+				base := "http://" + r.Host
+				switch r.URL.Path {
+				case "/mcp":
+					w.Header().Set("WWW-Authenticate", `Bearer resource_metadata="`+base+`/metadata"`)
+					w.WriteHeader(http.StatusUnauthorized)
+				case "/metadata":
+					_ = json.NewEncoder(w).Encode(map[string]any{
+						"resource":              base + "/mcp",
+						"authorization_servers": []string{authorizationServer.URL},
+					})
+				}
+			}))
+			defer resourceServer.Close()
+
+			_, err := resolveAuthorizationServer(context.Background(), resourceServer.Client(), resourceServer.URL+"/mcp", OAuthConfig{})
+			if err == nil || !strings.Contains(err.Error(), "issuer does not match") {
+				t.Fatalf("error = %v, want whitespace issuer mismatch", err)
+			}
+		})
+	}
+}
+
+func TestAuthorizationServerMetadataDoesNotFollowRedirects(t *testing.T) {
+	var redirectedHits atomic.Int64
+	redirected := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		redirectedHits.Add(1)
+		base := "http://" + r.Host
+		_ = json.NewEncoder(w).Encode(map[string]any{
+			"issuer":                 base,
+			"authorization_endpoint": base + "/authorize",
+			"token_endpoint":         base + "/token",
+		})
+	}))
+	defer redirected.Close()
+	authorizationServer := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		http.Redirect(w, r, redirected.URL+"/.well-known/oauth-authorization-server", http.StatusFound)
+	}))
+	defer authorizationServer.Close()
+	resourceServer := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		base := "http://" + r.Host
+		switch r.URL.Path {
+		case "/mcp":
+			w.Header().Set("WWW-Authenticate", `Bearer resource_metadata="`+base+`/metadata"`)
+			w.WriteHeader(http.StatusUnauthorized)
+		case "/metadata":
+			_ = json.NewEncoder(w).Encode(map[string]any{
+				"resource":              base + "/mcp",
+				"authorization_servers": []string{authorizationServer.URL},
+			})
+		}
+	}))
+	defer resourceServer.Close()
+
+	_, err := resolveAuthorizationServer(context.Background(), resourceServer.Client(), resourceServer.URL+"/mcp", OAuthConfig{})
+	if err == nil {
+		t.Fatal("authorization metadata redirect should fail")
+	}
+	if redirectedHits.Load() != 0 {
+		t.Fatalf("authorization metadata fetch followed redirect %d time(s)", redirectedHits.Load())
+	}
+}

internal/mcp/oauth_test.go

@@ -10,6 +10,7 @@ import (
 	"net/http/httptest"
 	"net/url"
 	"strings"
+	"sync/atomic"
 	"testing"
 	"time"
 
@@ -145,6 +146,130 @@ func TestResolveEndpointsConfigOverridesDiscovery(t *testing.T) {
 	}
 }
 
+func TestResolveAuthorizationServerUsesProtectedResourceMetadata(t *testing.T) {
+	var authorizationMetadataHits atomic.Int64
+	authorizationServer := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if r.URL.Path != "/.well-known/oauth-authorization-server" {
+			http.NotFound(w, r)
+			return
+		}
+		authorizationMetadataHits.Add(1)
+		base := "http://" + r.Host
+		_ = json.NewEncoder(w).Encode(map[string]any{
+			"issuer":                 base,
+			"authorization_endpoint": base + "/authorize",
+			"token_endpoint":         base + "/token",
+			"registration_endpoint":  base + "/register",
+		})
+	}))
+	defer authorizationServer.Close()
+
+	var resourceProbeHits, resourceMetadataHits atomic.Int64
+	resourceServer := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		switch r.URL.Path {
+		case "/mcp":
+			resourceProbeHits.Add(1)
+			metadataURL := "http://" + r.Host + "/resource-metadata"
+			w.Header().Set("WWW-Authenticate", `Bearer realm="OAuth", resource_metadata="`+metadataURL+`"`)
+			w.WriteHeader(http.StatusUnauthorized)
+		case "/resource-metadata":
+			resourceMetadataHits.Add(1)
+			_ = json.NewEncoder(w).Encode(map[string]any{
+				"resource":              "http://" + r.Host + "/mcp",
+				"authorization_servers": []string{authorizationServer.URL},
+			})
+		default:
+			http.NotFound(w, r)
+		}
+	}))
+	defer resourceServer.Close()
+
+	metadata, err := resolveAuthorizationServer(context.Background(), resourceServer.Client(), resourceServer.URL+"/mcp", OAuthConfig{})
+	if err != nil {
+		t.Fatalf("resolveAuthorizationServer() error = %v", err)
+	}
+	if metadata.Issuer != authorizationServer.URL {
+		t.Fatalf("issuer = %q, want %q", metadata.Issuer, authorizationServer.URL)
+	}
+	if metadata.AuthorizationEndpoint != authorizationServer.URL+"/authorize" || metadata.TokenEndpoint != authorizationServer.URL+"/token" {
+		t.Fatalf("resolved metadata = %#v", metadata)
+	}
+	if resourceProbeHits.Load() != 1 || resourceMetadataHits.Load() != 1 || authorizationMetadataHits.Load() != 1 {
+		t.Fatalf("discovery hits = probe:%d resource:%d authorization:%d", resourceProbeHits.Load(), resourceMetadataHits.Load(), authorizationMetadataHits.Load())
+	}
+}
+
+func TestResolveAuthorizationServerFallsBackToDirectDiscovery(t *testing.T) {
+	var resourceProbeHits, directDiscoveryHits atomic.Int64
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		switch r.URL.Path {
+		case "/mcp":
+			resourceProbeHits.Add(1)
+			w.Header().Set("Content-Type", "text/event-stream")
+			w.WriteHeader(http.StatusOK)
+			if flusher, ok := w.(http.Flusher); ok {
+				flusher.Flush()
+			}
+			<-r.Context().Done()
+		case "/.well-known/oauth-authorization-server/mcp":
+			directDiscoveryHits.Add(1)
+			base := "http://" + r.Host
+			_ = json.NewEncoder(w).Encode(map[string]any{
+				"issuer":                 base + "/mcp",
+				"authorization_endpoint": base + "/authorize",
+				"token_endpoint":         base + "/token",
+			})
+		default:
+			http.NotFound(w, r)
+		}
+	}))
+	defer server.Close()
+
+	metadata, err := resolveAuthorizationServer(context.Background(), server.Client(), server.URL+"/mcp", OAuthConfig{})
+	if err != nil {
+		t.Fatalf("resolveAuthorizationServer() error = %v", err)
+	}
+	if metadata.AuthorizationEndpoint != server.URL+"/authorize" || metadata.TokenEndpoint != server.URL+"/token" {
+		t.Fatalf("resolved metadata = %#v", metadata)
+	}
+	if resourceProbeHits.Load() != 1 || directDiscoveryHits.Load() != 1 {
+		t.Fatalf("discovery hits = probe:%d direct:%d", resourceProbeHits.Load(), directDiscoveryHits.Load())
+	}
+}
+
+func TestResolveAuthorizationServerIssuerOverrideSkipsResourceProbe(t *testing.T) {
+	var resourceProbeHits, issuerDiscoveryHits atomic.Int64
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		base := "http://" + r.Host
+		switch r.URL.Path {
+		case "/mcp":
+			resourceProbeHits.Add(1)
+			w.WriteHeader(http.StatusUnauthorized)
+		case "/.well-known/oauth-authorization-server/issuer":
+			issuerDiscoveryHits.Add(1)
+			_ = json.NewEncoder(w).Encode(map[string]any{
+				"issuer":                 base + "/issuer",
+				"authorization_endpoint": base + "/authorize",
+				"token_endpoint":         base + "/token",
+			})
+		default:
+			http.NotFound(w, r)
+		}
+	}))
+	defer server.Close()
+
+	metadata, err := resolveAuthorizationServer(context.Background(), server.Client(), server.URL+"/mcp", OAuthConfig{IssuerURL: server.URL + "/issuer"})
+	if err != nil {
+		t.Fatalf("resolveAuthorizationServer() error = %v", err)
+	}
+	if metadata.AuthorizationEndpoint != server.URL+"/authorize" || metadata.TokenEndpoint != server.URL+"/token" {
+		t.Fatalf("resolved metadata = %#v", metadata)
+	}
+	if resourceProbeHits.Load() != 0 || issuerDiscoveryHits.Load() != 1 {
+		t.Fatalf("discovery hits = resource:%d issuer:%d", resourceProbeHits.Load(), issuerDiscoveryHits.Load())
+	}
+}
+
 func TestPKCEChallengeIsS256OfVerifier(t *testing.T) {
 	pkce, err := newPKCE()
 	if err != nil {
@@ -448,3 +573,98 @@ func TestFullFlowStoresTokens(t *testing.T) {
 		t.Fatalf("login token = %#v", result)
 	}
 }
+
+func TestFullFlowUsesProtectedResourceDiscovery(t *testing.T) {
+	var resourceProbeHits, resourceMetadataHits, authorizationMetadataHits, tokenHits atomic.Int64
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		base := "http://" + r.Host
+		switch r.URL.Path {
+		case "/mcp":
+			resourceProbeHits.Add(1)
+			if r.Header.Get("Authorization") != "" || r.Header.Get("Cookie") != "" {
+				t.Error("resource probe sent credentials")
+			}
+			w.Header().Set("WWW-Authenticate", `Bearer resource_metadata="`+base+`/resource-metadata"`)
+			w.WriteHeader(http.StatusUnauthorized)
+		case "/resource-metadata":
+			resourceMetadataHits.Add(1)
+			_ = json.NewEncoder(w).Encode(map[string]any{
+				"resource":              base + "/mcp",
+				"authorization_servers": []string{base},
+			})
+		case "/.well-known/oauth-authorization-server":
+			authorizationMetadataHits.Add(1)
+			_ = json.NewEncoder(w).Encode(map[string]any{
+				"issuer":                 base,
+				"authorization_endpoint": base + "/authorize",
+				"token_endpoint":         base + "/token",
+			})
+		case "/token":
+			tokenHits.Add(1)
+			if err := r.ParseForm(); err != nil {
+				t.Errorf("parse token form: %v", err)
+			}
+			if r.Form.Get("code") != "authorization-code-secret" || r.Form.Get("code_verifier") == "" {
+				t.Error("token exchange omitted the authorization code or PKCE verifier")
+			}
+			_ = json.NewEncoder(w).Encode(map[string]any{
+				"access_token":  "access-token-secret",
+				"refresh_token": "refresh-token-secret",
+				"token_type":    "Bearer",
+				"expires_in":    3600,
+			})
+		default:
+			http.NotFound(w, r)
+		}
+	}))
+	defer server.Close()
+
+	opener := func(authURL string) error {
+		parsed, err := url.Parse(authURL)
+		if err != nil {
+			return err
+		}
+		if parsed.Path != "/authorize" || parsed.Query().Get("code_challenge_method") != "S256" || parsed.Query().Get("code_challenge") == "" {
+			return errors.New("authorization request omitted the discovered endpoint or PKCE challenge")
+		}
+		if parsed.Query().Get("code") != "" || parsed.Query().Get("code_verifier") != "" {
+			return errors.New("authorization request exposed an authorization code or PKCE verifier")
+		}
+		state := parsed.Query().Get("state")
+		redirect := parsed.Query().Get("redirect_uri")
+		go func() {
+			callbackURL := redirect + "?code=authorization-code-secret&state=" + url.QueryEscape(state)
+			for attempt := 0; attempt < 20; attempt++ {
+				response, requestErr := http.Get(callbackURL)
+				if requestErr == nil {
+					response.Body.Close()
+					return
+				}
+				time.Sleep(50 * time.Millisecond)
+			}
+		}()
+		return nil
+	}
+
+	token, err := Login(context.Background(), LoginOptions{
+		ServerName: "notion-style",
+		ServerURL:  server.URL + "/mcp",
+		Config: OAuthConfig{
+			ClientID: "client-123",
+			Scopes:   []string{"read"},
+		},
+		HTTPClient:  server.Client(),
+		OpenBrowser: opener,
+		Timeout:     5 * time.Second,
+		Now:         time.Now,
+	})
+	if err != nil {
+		t.Fatalf("Login() error = %v", err)
+	}
+	if token.AccessToken != "access-token-secret" || token.RefreshToken != "refresh-token-secret" {
+		t.Fatal("login did not return the issued tokens")
+	}
+	if resourceProbeHits.Load() != 1 || resourceMetadataHits.Load() != 1 || authorizationMetadataHits.Load() != 1 || tokenHits.Load() != 1 {
+		t.Fatalf("flow hits = probe:%d resource:%d authorization:%d token:%d", resourceProbeHits.Load(), resourceMetadataHits.Load(), authorizationMetadataHits.Load(), tokenHits.Load())
+	}
+}

internal/providerhealth/providerhealth.go

@@ -19,6 +19,7 @@ import (
 	"github.com/Gitlawb/zero/internal/providercatalog"
 	"github.com/Gitlawb/zero/internal/providers"
 	"github.com/Gitlawb/zero/internal/providers/providerio"
+	"github.com/Gitlawb/zero/internal/proxydial"
 	"github.com/Gitlawb/zero/internal/redaction"
 )
 
@@ -518,9 +519,15 @@ func newConnectivityClient(timeout time.Duration, resolver Resolver, sensitiveHe
 		transport = &http.Transport{}
 	}
 	transport.DialContext = safeDialContext(resolver, allowLoopbackOrPrivate)
+	// WRAPPED, SO THE DIALER LEARNS THE ROUTE THIS TRANSPORT CHOSE. The wrapper
+	// records the proxy selected for each request on that request, and the
+	// dialer reads it back on the dial that request causes; installing the bare
+	// transport instead would leave a proxied dial looking like a loopback
+	// target and fail the probe (#569). The cloned default transport already
+	// reads HTTPS_PROXY and friends; nothing new is enabled.
 	return &http.Client{
 		Timeout:   timeout,
-		Transport: transport,
+		Transport: proxydial.Wrap(transport),
 		CheckRedirect: func(req *http.Request, via []*http.Request) error {
 			if len(via) >= maxConnectivityRedirects {
 				return fmt.Errorf("provider connectivity exceeded %d redirects", maxConnectivityRedirects)
@@ -583,6 +590,17 @@ func sensitiveAuthHeaderNames(profile config.ProviderProfile, kind config.Provid
 func safeDialContext(resolver Resolver, allowLoopbackOrPrivate bool) func(context.Context, string, string) (net.Conn, error) {
 	dialer := &net.Dialer{Timeout: 10 * time.Second, KeepAlive: 30 * time.Second}
 	return func(ctx context.Context, network, address string) (net.Conn, error) {
+		// THE PROXY IS NOT THE TARGET. With HTTPS_PROXY set to a local forward
+		// proxy, the transport dials the proxy first and tunnels the request
+		// through it, and this dialer used to refuse that dial as a loopback
+		// address: "proxyconnect tcp: ... loopback hosts are blocked" for a
+		// request whose real target had already been validated (#569). The
+		// target validation is unchanged; only the dial the transport opens to
+		// the proxy it picked for this very request is let past the guard, and a
+		// direct dial is checked as it always was.
+		if proxydial.IsProxyDial(ctx) {
+			return dialer.DialContext(ctx, network, address)
+		}
 		host, port, err := net.SplitHostPort(address)
 		if err != nil {
 			return nil, err

internal/providerhealth/proxy_dial_test.go

@@ -0,0 +1,218 @@
+package providerhealth
+
+import (
+	"context"
+	"errors"
+	"net"
+	"net/http"
+	"net/netip"
+	"net/url"
+	"strconv"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/Gitlawb/zero/internal/proxydial"
+)
+
+// connectivityClientWithProxy builds the real connectivity client and swaps in
+// a proxy function, which is how the transport learns its route. The
+// environment is left alone deliberately: http.ProxyFromEnvironment reads it
+// once per process, so an environment-driven test would depend on test order.
+func connectivityClientWithProxy(t *testing.T, resolver Resolver, proxyFor func(*http.Request) (*url.URL, error)) *http.Client {
+	t.Helper()
+	client := newConnectivityClient(3*time.Second, resolver, nil, false)
+	wrapped, ok := client.Transport.(*proxydial.Transport)
+	if !ok {
+		t.Fatalf("transport = %T, want the route-recording wrapper; without it no dial can be recognised as the proxy dial", client.Transport)
+	}
+	wrapped.Proxy = proxyFor
+	return client
+}
+
+// recordingProxy is a listener standing in for a local forward proxy. It
+// records the first line it receives and hangs up.
+func recordingProxy(t *testing.T) (*url.URL, <-chan string) {
+	t.Helper()
+	listener, err := net.Listen("tcp", "127.0.0.1:0")
+	if err != nil {
+		t.Fatal(err)
+	}
+	t.Cleanup(func() { _ = listener.Close() })
+	arrived := make(chan string, 1)
+	go func() {
+		conn, err := listener.Accept()
+		if err != nil {
+			return
+		}
+		defer conn.Close()
+		buffer := make([]byte, 256)
+		n, _ := conn.Read(buffer)
+		arrived <- string(buffer[:n])
+	}()
+	proxyURL, err := url.Parse("http://" + listener.Addr().String())
+	if err != nil {
+		t.Fatal(err)
+	}
+	return proxyURL, arrived
+}
+
+// THE PROXY IS NOT THE TARGET, AND THE GUARD HAS TO KNOW THE DIFFERENCE.
+//
+// With HTTPS_PROXY set to a local forward proxy, the transport dials the proxy
+// first and tunnels the request through it. This dialer refused that dial as a
+// loopback address, so `zero doctor --connectivity` failed with "proxyconnect
+// tcp: ... loopback hosts are blocked" for a target that had already been
+// validated and was public (#569). Driven through the real client, so the route
+// is the transport's own decision.
+func TestConnectivityClientTunnelsThroughTheConfiguredProxy(t *testing.T) {
+	proxyURL, arrived := recordingProxy(t)
+	client := connectivityClientWithProxy(t,
+		staticResolver{err: errors.New("resolver must not be called for a proxied request")},
+		func(*http.Request) (*url.URL, error) { return proxyURL, nil })
+
+	request, err := http.NewRequestWithContext(context.Background(), http.MethodGet, "https://api.example.com/v1/models", nil)
+	if err != nil {
+		t.Fatal(err)
+	}
+	_, err = client.Do(request)
+	select {
+	case first := <-arrived:
+		if line := strings.SplitN(first, "\r\n", 2)[0]; line != "CONNECT api.example.com:443 HTTP/1.1" {
+			t.Fatalf("proxy received %q, want a CONNECT for the validated target", line)
+		}
+	case <-time.After(5 * time.Second):
+		t.Fatalf("the proxy never received a connection; request error: %v", err)
+	}
+}
+
+// AND A DIRECT REQUEST STAYS GUARDED, EVEN WHEN ITS ORIGIN IS THE PROXY'S OWN
+// ADDRESS.
+//
+// This is the NO_PROXY shape: the proxy function sends one host direct. An
+// exemption derived from asking that function about a request of our own
+// invention would answer "proxied" for the excluded host too, and this dial,
+// whose address equals the configured proxy endpoint, would skip the resolver
+// and reach whatever the name resolves to at connect time.
+func TestDirectRequestToTheProxyEndpointIsStillGuarded(t *testing.T) {
+	proxyURL, err := url.Parse("http://rebind.example:80")
+	if err != nil {
+		t.Fatal(err)
+	}
+	lookups := 0
+	resolver := countingResolver{
+		onLookup: func() { lookups++ },
+		addr:     netip.MustParseAddr("10.0.0.5"),
+	}
+	client := connectivityClientWithProxy(t, resolver, func(request *http.Request) (*url.URL, error) {
+		if request.URL.Hostname() == "rebind.example" {
+			return nil, nil
+		}
+		return proxyURL, nil
+	})
+
+	request, err := http.NewRequestWithContext(context.Background(), http.MethodGet, "http://rebind.example/data", nil)
+	if err != nil {
+		t.Fatal(err)
+	}
+	_, err = client.Do(request)
+
+	if lookups == 0 {
+		t.Fatal("the direct dial skipped the safety resolver because its address matched the configured proxy endpoint")
+	}
+	var safety endpointSafetyError
+	if !errors.As(err, &safety) {
+		t.Fatalf("err = %v, want the private answer to be refused", err)
+	}
+}
+
+// A proxy configured with a Unicode hostname is dialed by its IDNA-encoded
+// name, and it is still the proxy: the request must reach it rather than be
+// refused as an ordinary private address.
+func TestUnicodeProxyHostnameIsStillTheProxy(t *testing.T) {
+	dialed := ""
+	client := connectivityClientWithProxy(t,
+		staticResolver{err: errors.New("resolver must not be called for a proxied request")},
+		func(*http.Request) (*url.URL, error) { return url.Parse("http://büro.example:3067") })
+	wrapped := client.Transport.(*proxydial.Transport)
+	guarded := wrapped.DialContext
+	wrapped.DialContext = func(ctx context.Context, network, address string) (net.Conn, error) {
+		dialed = address
+		return guarded(ctx, network, address)
+	}
+
+	request, err := http.NewRequestWithContext(context.Background(), http.MethodGet, "https://api.example.com/v1/models", nil)
+	if err != nil {
+		t.Fatal(err)
+	}
+	_, err = client.Do(request)
+
+	if dialed != "xn--bro-hoa.example:3067" {
+		t.Fatalf("SETUP INVALID: dialed %q, want the IDNA-encoded proxy endpoint", dialed)
+	}
+	var safety endpointSafetyError
+	if errors.As(err, &safety) {
+		t.Fatalf("the configured proxy was refused by the guard: %v", err)
+	}
+}
+
+// Without a proxy the guard is exactly what it was: loopback is refused.
+func TestSafeDialContextStillRefusesLoopbackWithoutAProxy(t *testing.T) {
+	dial := safeDialContext(staticResolver{err: errors.New("resolver must not be called")}, false)
+	conn, err := dial(context.Background(), "tcp", "127.0.0.1:3067")
+	if conn != nil {
+		_ = conn.Close()
+		t.Fatal("loopback was dialed with no proxy configured")
+	}
+	var safety endpointSafetyError
+	if !errors.As(err, &safety) {
+		t.Fatalf("err = %v, want endpointSafetyError", err)
+	}
+}
+
+// A sibling loopback port is not the proxy, and the guard is unchanged for it.
+func TestSafeDialContextRefusesALoopbackPortThatIsNotTheProxy(t *testing.T) {
+	proxyURL, arrived := recordingProxy(t)
+	client := connectivityClientWithProxy(t,
+		staticResolver{err: errors.New("resolver must not be called")},
+		func(request *http.Request) (*url.URL, error) {
+			// Only the https probe is proxied; the http one below is direct and
+			// happens to point at the neighbouring port.
+			if request.URL.Scheme == "https" {
+				return proxyURL, nil
+			}
+			return nil, nil
+		})
+
+	_, port, _ := net.SplitHostPort(proxyURL.Host)
+	number, _ := strconv.Atoi(port)
+	sibling := "http://" + net.JoinHostPort("127.0.0.1", strconv.Itoa(number+1)) + "/"
+	request, err := http.NewRequestWithContext(context.Background(), http.MethodGet, sibling, nil)
+	if err != nil {
+		t.Fatal(err)
+	}
+	_, err = client.Do(request)
+	var safety endpointSafetyError
+	if !errors.As(err, &safety) {
+		t.Fatalf("err = %v, want a loopback port beside the proxy to stay blocked", err)
+	}
+	select {
+	case first := <-arrived:
+		t.Fatalf("the proxy received a connection it should not have: %q", first)
+	default:
+	}
+}
+
+// countingResolver answers with one address and reports each lookup, so a test
+// can tell a skipped guard from a guard that ran and allowed the address.
+type countingResolver struct {
+	onLookup func()
+	addr     netip.Addr
+}
+
+func (resolver countingResolver) LookupNetIP(context.Context, string, string) ([]netip.Addr, error) {
+	if resolver.onLookup != nil {
+		resolver.onLookup()
+	}
+	return []netip.Addr{resolver.addr}, nil
+}

internal/proxydial/proxydial.go

@@ -0,0 +1,93 @@
+// Package proxydial answers one question for an SSRF-guarded dialer: is this
+// dial the connection dial of a request the transport routed through a forward
+// proxy?
+//
+// A guarded transport validates the TARGET of a request before dialing, and its
+// dialer refuses loopback, private and link-local addresses so a redirect or a
+// DNS rebind cannot walk the request onto the local network. When a forward
+// proxy is configured, the transport dials the PROXY first and tunnels the
+// request through it, and a local proxy is by far the common shape:
+// HTTPS_PROXY=http://127.0.0.1:3067. The dialer then sees 127.0.0.1, refuses it,
+// and the user gets "loopback hosts are blocked" for a request whose real target
+// was validated and public (#569).
+//
+// The proxy address is not the request target, and the guard was never about it.
+// It is configuration the user set on purpose, and the transport is going to dial
+// it for every request whether the guard likes it or not. So that dial is let
+// through, and only that dial.
+//
+// THE EXEMPTION FOLLOWS THE TRANSPORT'S OWN ROUTE DECISION, NOT A GUESS AT IT.
+// Asking the Proxy function a question of one's own invention answers for a
+// request the transport never made: with NO_PROXY excluding a host, the real
+// request to that host goes direct while a synthetic probe still comes back
+// proxied, and a direct dial whose address happens to equal the proxy endpoint
+// would then skip the guard entirely. Host-dependent proxy callbacks make the
+// mismatch general, and no amount of care over the probe's spelling closes it,
+// because the two calls are about different requests.
+//
+// So the decision is recorded where it is made, on the request, and read back on
+// the dial that request causes. Transport.RoundTrip asks the wrapped transport's
+// Proxy function about the actual request, stores the answer in that request's
+// context, and hands it on; the transport derives the dial context from the
+// request context, so the dialer reads back the route this very connection is
+// being opened for. Per-request, so concurrent requests cannot overwrite each
+// other, and unforgeable from outside the package: the context key is private.
+package proxydial
+
+import (
+	"context"
+	"net/http"
+	"net/url"
+)
+
+// selectedProxyKey addresses the route decision inside a request context. It is
+// unexported so nothing outside this package can plant one.
+type selectedProxyKey struct{}
+
+// Transport records the proxy its wrapped transport selects for each request in
+// that request's context, so a guarded DialContext installed on the same
+// transport can tell the dial to a proxy from a direct dial.
+//
+// The embedded transport stays reachable: callers configure Proxy, DialContext
+// and the rest on it exactly as before, and tests can read them back.
+type Transport struct {
+	*http.Transport
+}
+
+// Wrap returns a Transport around transport. The result is the http.RoundTripper
+// to install on the client; installing the bare transport instead leaves every
+// dial looking direct, which is safe (the guard applies) but reopens #569.
+func Wrap(transport *http.Transport) *Transport {
+	return &Transport{Transport: transport}
+}
+
+// RoundTrip resolves the route for this request and passes the decision down to
+// the dialer through the request context.
+func (transport *Transport) RoundTrip(request *http.Request) (*http.Response, error) {
+	if transport.Transport.Proxy != nil {
+		// A Proxy error is left for the transport to report: it fails the
+		// request before dialing, so there is no dial to classify. The function
+		// is called once here and once by the transport, which is what a
+		// host-dependent callback already expects from redirects and retries.
+		if proxyURL, err := transport.Transport.Proxy(request); err == nil && proxyURL != nil {
+			request = request.WithContext(context.WithValue(request.Context(), selectedProxyKey{}, proxyURL))
+		}
+	}
+	return transport.Transport.RoundTrip(request)
+}
+
+// IsProxyDial reports whether ctx belongs to a request this package's Transport
+// routed through a proxy, which makes the dial about to happen the dial to that
+// proxy.
+//
+// THE ADDRESS IS NOT COMPARED, AND DOES NOT NEED TO BE. A transport opens
+// exactly one connection dial per connection, and when a proxy is selected that
+// dial goes to the proxy; the target is reached through it, never dialed. So the
+// route decision on the context already identifies the dial, and matching the
+// address against the proxy URL on top of it could only ever disagree with the
+// transport, which is what a punycoded Unicode proxy hostname does: Go dials
+// xn--bro-hoa.example while the URL still spells buero as the user wrote it.
+func IsProxyDial(ctx context.Context) bool {
+	proxyURL, _ := ctx.Value(selectedProxyKey{}).(*url.URL)
+	return proxyURL != nil
+}

internal/proxydial/proxydial_test.go

@@ -0,0 +1,224 @@
+package proxydial
+
+import (
+	"context"
+	"errors"
+	"net"
+	"net/http"
+	"net/url"
+	"sync"
+	"testing"
+)
+
+// errDialed ends the request at the dial, after the route decision has been
+// observed. Nothing here needs a live server.
+var errDialed = errors.New("dial recorded")
+
+type dialRecord struct {
+	address string
+	proxied bool
+}
+
+// driveRequest sends one request through a wrapped transport whose dialer
+// records what it was asked for and whether the context says this dial belongs
+// to a proxied request.
+func driveRequest(t *testing.T, target string, proxyFor func(*http.Request) (*url.URL, error)) dialRecord {
+	t.Helper()
+	var record dialRecord
+	transport := &http.Transport{Proxy: proxyFor}
+	transport.DialContext = func(ctx context.Context, _, address string) (net.Conn, error) {
+		record = dialRecord{address: address, proxied: IsProxyDial(ctx)}
+		return nil, errDialed
+	}
+	client := &http.Client{Transport: Wrap(transport)}
+	request, err := http.NewRequest(http.MethodGet, target, nil)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if _, err := client.Do(request); !errors.Is(err, errDialed) {
+		t.Fatalf("%s: request ended before the dial: %v", target, err)
+	}
+	if record.address == "" {
+		t.Fatalf("%s: the dialer was never called", target)
+	}
+	return record
+}
+
+func fixedProxy(raw string) func(*http.Request) (*url.URL, error) {
+	parsed, err := url.Parse(raw)
+	if err != nil {
+		panic(err)
+	}
+	return func(*http.Request) (*url.URL, error) { return parsed, nil }
+}
+
+// THE DIAL TO A CONFIGURED PROXY IS THE ONE THAT IS EXEMPT. A proxied request
+// dials the proxy, never the target, so the route on the context is what
+// identifies the dial.
+func TestProxiedRequestDialsTheProxyAndSaysSo(t *testing.T) {
+	record := driveRequest(t, "https://api.example.com/v1/models", fixedProxy("http://127.0.0.1:3067"))
+	if !record.proxied {
+		t.Error("a request routed through a proxy did not reach the dialer as proxied")
+	}
+	if record.address != "127.0.0.1:3067" {
+		t.Errorf("dial address = %q, want the proxy endpoint", record.address)
+	}
+}
+
+// AND A DIRECT REQUEST IS NOT, EVEN WHEN ITS ORIGIN IS THE PROXY'S OWN ADDRESS.
+//
+// This is the NO_PROXY shape: the proxy function excludes one host, so a request
+// to that host goes direct. Asking that same function about a request of our own
+// invention would answer "proxied" (the invented host is not excluded) and the
+// direct dial, whose address equals the proxy endpoint, would skip the guard
+// while resolving to whatever the name resolves to at connect time.
+func TestDirectRequestToTheProxyEndpointIsNotAProxyDial(t *testing.T) {
+	proxyURL, err := url.Parse("http://rebind.example:80")
+	if err != nil {
+		t.Fatal(err)
+	}
+	noProxyForRebind := func(request *http.Request) (*url.URL, error) {
+		if request.URL.Hostname() == "rebind.example" {
+			return nil, nil
+		}
+		return proxyURL, nil
+	}
+
+	record := driveRequest(t, "http://rebind.example/data", noProxyForRebind)
+	if record.address != "rebind.example:80" {
+		t.Fatalf("SETUP INVALID: dial address = %q, want the direct origin, which is also the proxy endpoint", record.address)
+	}
+	if record.proxied {
+		t.Error("a direct dial was reported as the proxy dial because its address matched the configured proxy")
+	}
+
+	// The same function still routes another host through that proxy, so the
+	// exclusion above is a route difference and not a disabled proxy.
+	if record := driveRequest(t, "http://elsewhere.example/data", noProxyForRebind); !record.proxied {
+		t.Error("the configured proxy was not used for a host outside the exclusion")
+	}
+}
+
+// The inverse mismatch: a callback that routes by host must not have its answer
+// taken from some other host. A proxy selected only for the real target is
+// honoured.
+func TestHostDependentProxySelectionIsHonoured(t *testing.T) {
+	proxyURL, err := url.Parse("http://127.0.0.1:3067")
+	if err != nil {
+		t.Fatal(err)
+	}
+	onlyForOneHost := func(request *http.Request) (*url.URL, error) {
+		if request.URL.Hostname() == "api.example.com" {
+			return proxyURL, nil
+		}
+		return nil, nil
+	}
+	if record := driveRequest(t, "https://api.example.com/v1", onlyForOneHost); !record.proxied || record.address != "127.0.0.1:3067" {
+		t.Errorf("selected proxy not reached: %+v", record)
+	}
+	if record := driveRequest(t, "https://other.example/v1", onlyForOneHost); record.proxied {
+		t.Error("an unproxied host was reported as proxied")
+	}
+}
+
+// Scheme separation: an https-only proxy leaves an http request direct, and the
+// decision recorded is the one made for that request's own scheme.
+func TestSchemeSeparation(t *testing.T) {
+	proxyURL, err := url.Parse("http://127.0.0.1:3067")
+	if err != nil {
+		t.Fatal(err)
+	}
+	httpsOnly := func(request *http.Request) (*url.URL, error) {
+		if request.URL.Scheme == "https" {
+			return proxyURL, nil
+		}
+		return nil, nil
+	}
+	if record := driveRequest(t, "https://api.example.com/v1", httpsOnly); !record.proxied {
+		t.Error("the https proxy was not applied to an https request")
+	}
+	if record := driveRequest(t, "http://api.example.com/v1", httpsOnly); record.proxied {
+		t.Error("an http request was treated as proxied by an https-only proxy")
+	}
+}
+
+// A UNICODE PROXY HOSTNAME IS STILL THE PROXY. Go dials proxies by their
+// IDNA-encoded name, so a matcher comparing the URL's own spelling would call
+// this dial direct and refuse it as an ordinary private address. Nothing is
+// compared here, so both spellings of one host are one host.
+func TestUnicodeProxyHostnameIsRecognised(t *testing.T) {
+	unicodeRecord := driveRequest(t, "https://api.example.com/v1", fixedProxy("http://büro.example:3067"))
+	if !unicodeRecord.proxied {
+		t.Error("a proxy configured with a Unicode hostname was not recognised as the proxy")
+	}
+	asciiRecord := driveRequest(t, "https://api.example.com/v1", fixedProxy("http://xn--bro-hoa.example:3067"))
+	if !asciiRecord.proxied {
+		t.Error("a proxy configured with the ASCII spelling was not recognised as the proxy")
+	}
+	// The two spellings name one endpoint, and it is the ASCII one that is
+	// dialed. This is the mismatch a string comparison would have had to close.
+	if unicodeRecord.address != asciiRecord.address {
+		t.Errorf("dial addresses differ across spellings of one host: %q vs %q", unicodeRecord.address, asciiRecord.address)
+	}
+}
+
+// A transport with no proxy leaves every dial direct.
+func TestNoProxyMeansNoExemption(t *testing.T) {
+	if record := driveRequest(t, "http://127.0.0.1:3067/", nil); record.proxied {
+		t.Error("a dial was reported as proxied by a transport with no Proxy function")
+	}
+	if IsProxyDial(context.Background()) {
+		t.Error("a context that never went through the wrapper reported a proxy dial")
+	}
+}
+
+// THE DECISION IS PER REQUEST. A shared record of the last selected proxy would
+// let a proxied request hand its exemption to a direct one running beside it.
+func TestConcurrentRequestsKeepTheirOwnRoute(t *testing.T) {
+	proxyURL, err := url.Parse("http://127.0.0.1:3067")
+	if err != nil {
+		t.Fatal(err)
+	}
+	byHost := func(request *http.Request) (*url.URL, error) {
+		if request.URL.Hostname() == "proxied.example" {
+			return proxyURL, nil
+		}
+		return nil, nil
+	}
+
+	var mutex sync.Mutex
+	seen := map[string]bool{}
+	transport := &http.Transport{Proxy: byHost}
+	transport.DialContext = func(ctx context.Context, _, address string) (net.Conn, error) {
+		mutex.Lock()
+		seen[address] = IsProxyDial(ctx)
+		mutex.Unlock()
+		return nil, errDialed
+	}
+	client := &http.Client{Transport: Wrap(transport)}
+
+	var group sync.WaitGroup
+	for range 40 {
+		for _, target := range []string{"http://proxied.example/", "http://direct.example/"} {
+			group.Add(1)
+			go func() {
+				defer group.Done()
+				request, _ := http.NewRequest(http.MethodGet, target, nil)
+				_, _ = client.Do(request)
+			}()
+		}
+	}
+	group.Wait()
+
+	mutex.Lock()
+	defer mutex.Unlock()
+	if !seen["127.0.0.1:3067"] {
+		t.Error("the proxy dial was not recorded as proxied under concurrency")
+	}
+	if seen["direct.example:80"] {
+		t.Error("a direct dial picked up another request's proxy exemption")
+	}
+	if len(seen) != 2 {
+		t.Fatalf("SETUP INVALID: dialed %v, want exactly the proxy and the direct origin", seen)
+	}
+}

internal/sandbox/profile.go

@@ -96,15 +96,28 @@ var protectedMetadataNames = []string{".git", ".zero", ".agents"}
 // gitMetadataWriteCarveouts below.
 var sandboxFullyProtectedMetadataNames = []string{".zero", ".agents"}
 
-// gitMetadataWriteCarveouts returns the .git subpaths that stay write-denied
-// under the OS-level sandbox even though the rest of .git is writable to git
-// subprocesses. Nonexistent paths are harmless no-ops in every backend's
-// enforcement (seatbelt regex, bwrap ro-bind, Windows ACL deny entry).
+// gitMetadataWriteCarveouts returns the .git paths that stay write-denied under
+// the OS-level sandbox even though the rest of .git is writable to git
+// subprocesses. Worktrees and submodules store .git as a regular pointer file,
+// so they protect that file itself: constructing .git/hooks below it makes
+// bwrap fail before the command starts. All other entry and error states retain
+// the legacy child paths. The pointer is deliberately not parsed here;
+// repository-controlled metadata must not redirect sandbox rules elsewhere.
 func gitMetadataWriteCarveouts(root string) []string {
-	return []string{
-		filepath.Join(root, ".git", "hooks"),
-		filepath.Join(root, ".git", "config"),
+	return gitMetadataWriteCarveoutsWithLstat(root, os.Lstat)
+}
+
+func gitMetadataWriteCarveoutsWithLstat(root string, lstat func(string) (os.FileInfo, error)) []string {
+	gitPath := filepath.Join(root, ".git")
+	children := []string{
+		filepath.Join(gitPath, "hooks"),
+		filepath.Join(gitPath, "config"),
 	}
+	info, err := lstat(gitPath)
+	if err != nil || !info.Mode().IsRegular() {
+		return children
+	}
+	return []string{gitPath}
 }
 
 func PermissionProfileFromPolicy(workspaceRoot string, policy Policy, scope *Scope) PermissionProfile {

internal/sandbox/profile_worktree_test.go

@@ -0,0 +1,115 @@
+package sandbox
+
+import (
+	"errors"
+	"os"
+	"path/filepath"
+	"testing"
+)
+
+func mustEqualCarveouts(t *testing.T, got, want []string) {
+	t.Helper()
+	if len(got) != len(want) {
+		t.Fatalf("carveouts = %v, want %v", got, want)
+	}
+	for i := range want {
+		if got[i] != want[i] {
+			t.Fatalf("carveout[%d] = %q, want %q", i, got[i], want[i])
+		}
+	}
+}
+
+// Worktree/submodule checkouts store .git as a pointer file. Protect the file
+// itself and never create a bwrap mount target beneath it.
+func TestGitMetadataWriteCarveoutsProtectsWorktreePointer(t *testing.T) {
+	root := t.TempDir()
+	gitPath := filepath.Join(root, ".git")
+	if err := os.WriteFile(gitPath, []byte("gitdir: ../outside\n"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+
+	got := gitMetadataWriteCarveouts(root)
+	mustEqualCarveouts(t, got, []string{gitPath})
+	for _, carveout := range got {
+		if carveout == filepath.Join(gitPath, "hooks") || carveout == filepath.Join(gitPath, "config") {
+			t.Fatalf("carveout points beneath .git file: %q", carveout)
+		}
+	}
+}
+
+func TestLinuxBwrapPlanDoesNotMountBelowWorktreePointer(t *testing.T) {
+	root := t.TempDir()
+	gitPath := filepath.Join(root, ".git")
+	if err := os.WriteFile(gitPath, []byte("gitdir: ../outside\n"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	profile := PermissionProfile{FileSystem: FileSystemPolicy{
+		Kind: FileSystemRestricted,
+		WriteRoots: []WritableRoot{{
+			Root:             root,
+			ReadOnlySubpaths: gitMetadataWriteCarveouts(root),
+		}},
+	}}
+	args := linuxBwrapFilesystemArgs(profile)
+	assertArgsContainSequence(t, args, "--ro-bind", gitPath, gitPath)
+	for _, child := range []string{"hooks", "config"} {
+		bogus := filepath.Join(gitPath, child)
+		if argsContainSequence(args, "--tmpfs", bogus) || argsContainSequence(args, "--ro-bind", bogus, bogus) {
+			t.Fatalf("bwrap args contain mount below .git file %q: %v", bogus, args)
+		}
+	}
+}
+
+func TestGitMetadataWriteCarveoutsPlainCheckout(t *testing.T) {
+	root := t.TempDir()
+	want := []string{
+		filepath.Join(root, ".git", "hooks"),
+		filepath.Join(root, ".git", "config"),
+	}
+	mustEqualCarveouts(t, gitMetadataWriteCarveouts(root), want)
+
+	if err := os.MkdirAll(filepath.Join(root, ".git"), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	mustEqualCarveouts(t, gitMetadataWriteCarveouts(root), want)
+}
+
+func TestGitMetadataWriteCarveoutsPreservesSymlinkBehavior(t *testing.T) {
+	for _, targetKind := range []string{"directory", "file", "dangling"} {
+		t.Run(targetKind, func(t *testing.T) {
+			root := t.TempDir()
+			target := filepath.Join(root, "real.git")
+			switch targetKind {
+			case "directory":
+				if err := os.MkdirAll(target, 0o755); err != nil {
+					t.Fatal(err)
+				}
+			case "file":
+				if err := os.WriteFile(target, []byte("gitdir: ../outside\n"), 0o644); err != nil {
+					t.Fatal(err)
+				}
+			}
+			if err := os.Symlink(target, filepath.Join(root, ".git")); err != nil {
+				t.Skipf("symlink unavailable: %v", err)
+			}
+			want := []string{
+				filepath.Join(root, ".git", "hooks"),
+				filepath.Join(root, ".git", "config"),
+			}
+			mustEqualCarveouts(t, gitMetadataWriteCarveouts(root), want)
+		})
+	}
+}
+
+func TestGitMetadataWriteCarveoutsPreservesInspectionErrorBehavior(t *testing.T) {
+	root := t.TempDir()
+	gitPath := filepath.Join(root, ".git")
+	want := []string{
+		filepath.Join(gitPath, "hooks"),
+		filepath.Join(gitPath, "config"),
+	}
+	got := gitMetadataWriteCarveoutsWithLstat(root, func(string) (os.FileInfo, error) {
+		return nil, errors.New("inspection failed")
+	})
+	mustEqualCarveouts(t, got, want)
+}

internal/sandbox/profile_worktree_unix_test.go

@@ -0,0 +1,21 @@
+//go:build unix
+
+package sandbox
+
+import (
+	"path/filepath"
+	"syscall"
+	"testing"
+)
+
+func TestGitMetadataWriteCarveoutsPreservesSpecialGitEntryBehavior(t *testing.T) {
+	root := t.TempDir()
+	gitPath := filepath.Join(root, ".git")
+	if err := syscall.Mkfifo(gitPath, 0o644); err != nil {
+		t.Skip(err)
+	}
+	mustEqualCarveouts(t, gitMetadataWriteCarveouts(root), []string{
+		filepath.Join(gitPath, "hooks"),
+		filepath.Join(gitPath, "config"),
+	})
+}

internal/specialist/exec.go

@@ -76,12 +76,17 @@ type BuildArgsInput struct {
 }
 
 type BuildResumeArgsInput struct {
-	SessionID      string
-	Prompt         string
-	CurrentDepth   int
-	Manifest       Manifest
-	Cwd            string
-	PermissionMode string
+	SessionID    string
+	Prompt       string
+	CurrentDepth int
+	Manifest     Manifest
+	Cwd          string
+	// ParentModel and ParentReasoningEffort are the same fallbacks the fresh
+	// path takes, and they are here for the same reason: appendModelArgs uses
+	// them only when the manifest pins nothing of its own.
+	ParentModel           string
+	ParentReasoningEffort string
+	PermissionMode        string
 }
 
 type BuildArgsResult struct {
@@ -344,6 +349,18 @@ func (executor Executor) BuildResumeArgs(input BuildResumeArgsInput) (BuildArgsR
 	}
 	args := []string{"exec", "--resume", sessionID}
 	args = append(args, promptArgs...)
+	// A RESUMED SPECIALIST KEEPS THE MODEL ITS MANIFEST PINNED.
+	//
+	// The fresh path appends this and the resume path did not, so a specialist
+	// pinned to a cheap model ran on that model once and then silently reverted
+	// to the parent's configured model on every resume. Nothing reports it: the
+	// child starts normally and the only symptom is the bill.
+	//
+	// Resuming does not restore the recorded model on its own. sessions.PrepareExec
+	// records the model it ran under but never feeds it back into provider
+	// construction, so without this the child takes whatever the config default
+	// resolves to now.
+	args = appendModelArgs(args, input.Manifest, input.ParentModel, input.ParentReasoningEffort)
 	args = append(args, "--auto", specialistAutonomy(input.PermissionMode), "--output-format", "stream-json")
 	// See BuildArgs: only plan/spec-draft propagate --permission-mode so --auto
 	// remains the authority for member/auto/ask/unsafe child resolution.
@@ -424,12 +441,14 @@ func (executor Executor) runResume(ctx context.Context, params TaskParameters, o
 		return ExecResult{}, err
 	}
 	built, err := executor.BuildResumeArgs(BuildResumeArgsInput{
-		SessionID:      params.Resume,
-		Prompt:         params.Prompt,
-		CurrentDepth:   options.CurrentDepth,
-		Manifest:       manifest,
-		Cwd:            options.Cwd,
-		PermissionMode: options.PermissionMode,
+		SessionID:             params.Resume,
+		Prompt:                params.Prompt,
+		CurrentDepth:          options.CurrentDepth,
+		Manifest:              manifest,
+		Cwd:                   options.Cwd,
+		ParentModel:           options.ParentModel,
+		ParentReasoningEffort: options.ParentReasoningEffort,
+		PermissionMode:        options.PermissionMode,
 	})
 	if err != nil {
 		return ExecResult{}, err

internal/specialist/resume_model_test.go

@@ -0,0 +1,303 @@
+package specialist
+
+import (
+	"context"
+	"strings"
+	"testing"
+
+	"github.com/Gitlawb/zero/internal/sessions"
+	"github.com/Gitlawb/zero/internal/streamjson"
+)
+
+// argValue returns the value following flag in argv, and whether it was present.
+func argValue(args []string, flag string) (string, bool) {
+	for index, arg := range args {
+		if arg == flag && index+1 < len(args) {
+			return args[index+1], true
+		}
+	}
+	return "", false
+}
+
+func pinnedManifest(model string, effort string) Manifest {
+	return Manifest{
+		Metadata: Metadata{
+			Name:            "skim",
+			Description:     "Bounded read-only lookups.",
+			Model:           model,
+			ReasoningEffort: effort,
+			Tools:           []string{"read_file"},
+		},
+		SystemPrompt:  "Find the thing and stop.",
+		ResolvedTools: []string{"read_file"},
+	}
+}
+
+// A RESUMED SPECIALIST KEEPS THE MODEL ITS MANIFEST PINNED.
+//
+// Metadata.Model exists so a bounded, delegated task can run on a cheaper model
+// than its parent. BuildArgs appended it; BuildResumeArgs did not. So the
+// specialist ran on the cheap model once, and the moment the orchestrator
+// resumed it the child fell back to whatever the parent's configured model
+// resolved to. Nothing surfaced it: the resumed child starts normally, does the
+// work, and the only symptom is the bill.
+//
+// Resuming does not restore the recorded model on its own, which is why the flag
+// has to be passed again rather than relied upon.
+func TestAResumedSpecialistKeepsItsPinnedModel(t *testing.T) {
+	manifest := pinnedManifest("claude-haiku-4.5", "")
+
+	fresh, err := (Executor{}).BuildArgs(BuildArgsInput{
+		Manifest:     manifest,
+		Prompt:       "find the thing",
+		CurrentDepth: 0,
+		ParentModel:  "claude-opus-4.1",
+	})
+	if err != nil {
+		t.Fatalf("BuildArgs: %v", err)
+	}
+	// SETUP: the fresh path really does pin it, or the comparison below is
+	// asserting against a path that never worked either.
+	freshModel, ok := argValue(fresh.Args, "--model")
+	if !ok || freshModel != "claude-haiku-4.5" {
+		t.Fatalf("SETUP INVALID: the fresh path passed --model %q (present=%t), want the manifest's model", freshModel, ok)
+	}
+
+	resumed, err := (Executor{}).BuildResumeArgs(BuildResumeArgsInput{
+		SessionID:    "01HZZZZZZZZZZZZZZZZZZZZZZZ",
+		Prompt:       "keep going",
+		CurrentDepth: 0,
+		Manifest:     manifest,
+		ParentModel:  "claude-opus-4.1",
+	})
+	if err != nil {
+		t.Fatalf("BuildResumeArgs: %v", err)
+	}
+	resumedModel, ok := argValue(resumed.Args, "--model")
+	if !ok {
+		t.Fatalf("a resumed specialist carries no --model at all, so it reverts to the parent's configured model: %v", resumed.Args)
+	}
+	if resumedModel != "claude-haiku-4.5" {
+		t.Fatalf("a resumed specialist runs on %q, want the manifest's pinned %q", resumedModel, "claude-haiku-4.5")
+	}
+}
+
+// And a manifest that pins nothing still inherits the parent's model, which is
+// what makes the fallback in appendModelArgs meaningful rather than the pinned
+// case being special-cased.
+func TestAResumedSpecialistWithNoPinInheritsTheParentModel(t *testing.T) {
+	resumed, err := (Executor{}).BuildResumeArgs(BuildResumeArgsInput{
+		SessionID:    "01HZZZZZZZZZZZZZZZZZZZZZZZ",
+		Prompt:       "keep going",
+		CurrentDepth: 0,
+		Manifest:     pinnedManifest("", ""),
+		ParentModel:  "claude-opus-4.1",
+	})
+	if err != nil {
+		t.Fatalf("BuildResumeArgs: %v", err)
+	}
+	model, ok := argValue(resumed.Args, "--model")
+	if !ok || model != "claude-opus-4.1" {
+		t.Fatalf("a resumed specialist with no pinned model passed --model %q (present=%t), want the parent's", model, ok)
+	}
+}
+
+// The reasoning-effort rule travels with the model, or the two paths disagree
+// about what a pinned model implies. appendModelArgs inherits the parent's
+// effort ONLY when the manifest pins no model of its own: a manifest that chose
+// a different model has not agreed to the parent's effort for it.
+func TestAResumedSpecialistFollowsTheSameReasoningEffortRule(t *testing.T) {
+	t.Run("pinned model does not inherit parent effort", func(t *testing.T) {
+		resumed, err := (Executor{}).BuildResumeArgs(BuildResumeArgsInput{
+			SessionID:             "01HZZZZZZZZZZZZZZZZZZZZZZZ",
+			Prompt:                "keep going",
+			CurrentDepth:          0,
+			Manifest:              pinnedManifest("claude-haiku-4.5", ""),
+			ParentModel:           "claude-opus-4.1",
+			ParentReasoningEffort: "high",
+		})
+		if err != nil {
+			t.Fatalf("BuildResumeArgs: %v", err)
+		}
+		if effort, ok := argValue(resumed.Args, "--reasoning-effort"); ok {
+			t.Fatalf("a manifest that pinned its own model inherited the parent's effort %q", effort)
+		}
+	})
+
+	t.Run("no pinned model inherits parent effort", func(t *testing.T) {
+		resumed, err := (Executor{}).BuildResumeArgs(BuildResumeArgsInput{
+			SessionID:             "01HZZZZZZZZZZZZZZZZZZZZZZZ",
+			Prompt:                "keep going",
+			CurrentDepth:          0,
+			Manifest:              pinnedManifest("", ""),
+			ParentModel:           "claude-opus-4.1",
+			ParentReasoningEffort: "high",
+		})
+		if err != nil {
+			t.Fatalf("BuildResumeArgs: %v", err)
+		}
+		effort, ok := argValue(resumed.Args, "--reasoning-effort")
+		if !ok || effort != "high" {
+			t.Fatalf("a manifest pinning nothing passed --reasoning-effort %q (present=%t), want the parent's", effort, ok)
+		}
+	})
+}
+
+// The two builders agree on where the flag sits relative to the rest of the
+// argv, so a future change to one does not silently reorder only the other.
+func TestBothBuildersPlaceTheModelBeforeTheAutonomyFlag(t *testing.T) {
+	manifest := pinnedManifest("claude-haiku-4.5", "")
+	fresh, err := (Executor{}).BuildArgs(BuildArgsInput{Manifest: manifest, Prompt: "go", CurrentDepth: 0})
+	if err != nil {
+		t.Fatalf("BuildArgs: %v", err)
+	}
+	resumed, err := (Executor{}).BuildResumeArgs(BuildResumeArgsInput{
+		SessionID: "01HZZZZZZZZZZZZZZZZZZZZZZZ", Prompt: "go", CurrentDepth: 0, Manifest: manifest,
+	})
+	if err != nil {
+		t.Fatalf("BuildResumeArgs: %v", err)
+	}
+	for _, argv := range [][]string{fresh.Args, resumed.Args} {
+		model := indexOf(argv, "--model")
+		auto := indexOf(argv, "--auto")
+		if model < 0 || auto < 0 || model > auto {
+			t.Fatalf("--model at %d, --auto at %d in %s", model, auto, strings.Join(argv, " "))
+		}
+	}
+}
+
+func indexOf(args []string, want string) int {
+	for index, arg := range args {
+		if arg == want {
+			return index
+		}
+	}
+	return -1
+}
+
+// AND THE CALL SITE PASSES IT, WHICH THE BUILDER TESTS ABOVE CANNOT SEE.
+//
+// Every test above calls BuildResumeArgs directly. Dropping the ParentModel
+// field from the runResume call site still compiles and still passes all of
+// them, because the builder is doing its job with whatever it is handed. The
+// defect this fix repairs lived at the call site, not in the builder, so it
+// needs a test that goes through Run.
+//
+// Driven through the real Run dispatch with the RunChild seam capturing argv.
+func TestRunResumePassesTheParentModelThroughToTheChild(t *testing.T) {
+	store := sessions.NewStore(sessions.StoreOptions{RootDir: t.TempDir()})
+	parent, err := store.Create(sessions.CreateInput{SessionID: "parent_session"})
+	if err != nil {
+		t.Fatalf("create parent: %v", err)
+	}
+	if _, err := store.Create(sessions.CreateInput{
+		SessionID:       "child_task",
+		SessionKind:     sessions.SessionKindChild,
+		Tag:             SessionTagSpecialist,
+		Depth:           1,
+		ParentSessionID: parent.SessionID,
+		AgentName:       "skim",
+		TaskID:          "child_task",
+	}); err != nil {
+		t.Fatalf("create child: %v", err)
+	}
+
+	zero := 0
+	var captured []string
+	executor := Executor{
+		BinaryPath:   "/usr/local/bin/zero",
+		SessionStore: store,
+		NewSessionID: func() (string, error) { return "child_task", nil },
+		Load: func(LoadOptions) (LoadResult, error) {
+			// No pinned model, so the parent's is the only thing that can supply one.
+			return LoadResult{Specialists: []Manifest{pinnedManifest("", "")}}, nil
+		},
+		RunChild: func(_ context.Context, _ string, args []string, _ func(streamjson.Event)) (ChildRunResult, error) {
+			captured = append([]string(nil), args...)
+			return ChildRunResult{
+				Events: []streamjson.Event{
+					{Type: streamjson.EventRunStart, RunID: "run_1", SessionID: "child_task"},
+					{Type: streamjson.EventFinal, RunID: "run_1", Text: "done"},
+					{Type: streamjson.EventRunEnd, RunID: "run_1", Status: "success", ExitCode: &zero},
+				},
+			}, nil
+		},
+	}
+
+	if _, err := executor.Run(context.Background(), TaskParameters{
+		Name:   "skim",
+		Prompt: "keep going",
+		Resume: "child_task",
+	}, TaskRunOptions{
+		ParentSessionID: parent.SessionID,
+		ParentModel:     "claude-opus-4.1",
+	}); err != nil {
+		t.Fatalf("Run(resume): %v", err)
+	}
+
+	// SETUP: this really was the resume path, not a fresh spawn.
+	if index := indexOf(captured, "--resume"); index < 0 {
+		t.Fatalf("SETUP INVALID: the child was not resumed: %v", captured)
+	}
+	model, ok := argValue(captured, "--model")
+	if !ok {
+		t.Fatalf("the resumed child was launched with no --model, so it runs on whatever the config default resolves to: %v", captured)
+	}
+	if model != "claude-opus-4.1" {
+		t.Fatalf("the resumed child was launched with --model %q, want the parent's %q", model, "claude-opus-4.1")
+	}
+}
+
+// THE FRESH CALL SITE NEEDS THE SAME GUARD, FOR THE SAME REASON.
+//
+// runFresh and runResume both construct their builder input by hand, and both
+// have a byte-identical ParentModel line. Deleting either one compiles. The
+// resume half is what this change repairs; this covers the other half so the
+// pair cannot drift again in the direction nobody was looking.
+func TestRunFreshPassesTheParentModelThroughToTheChild(t *testing.T) {
+	store := sessions.NewStore(sessions.StoreOptions{RootDir: t.TempDir()})
+	parent, err := store.Create(sessions.CreateInput{SessionID: "parent_session"})
+	if err != nil {
+		t.Fatalf("create parent: %v", err)
+	}
+
+	zero := 0
+	var captured []string
+	executor := Executor{
+		BinaryPath:   "/usr/local/bin/zero",
+		SessionStore: store,
+		NewSessionID: func() (string, error) { return "child_task", nil },
+		Load: func(LoadOptions) (LoadResult, error) {
+			return LoadResult{Specialists: []Manifest{pinnedManifest("", "")}}, nil
+		},
+		RunChild: func(_ context.Context, _ string, args []string, _ func(streamjson.Event)) (ChildRunResult, error) {
+			captured = append([]string(nil), args...)
+			return ChildRunResult{
+				Events: []streamjson.Event{
+					{Type: streamjson.EventRunStart, RunID: "run_1", SessionID: "child_task"},
+					{Type: streamjson.EventFinal, RunID: "run_1", Text: "done"},
+					{Type: streamjson.EventRunEnd, RunID: "run_1", Status: "success", ExitCode: &zero},
+				},
+			}, nil
+		},
+	}
+
+	if _, err := executor.Run(context.Background(), TaskParameters{
+		Name:   "skim",
+		Prompt: "find the thing",
+	}, TaskRunOptions{
+		ParentSessionID: parent.SessionID,
+		ParentModel:     "claude-opus-4.1",
+	}); err != nil {
+		t.Fatalf("Run(fresh): %v", err)
+	}
+
+	// SETUP: a fresh spawn, not a resume, or this covers the wrong site.
+	if indexOf(captured, "--resume") >= 0 {
+		t.Fatalf("SETUP INVALID: the child was resumed rather than freshly spawned: %v", captured)
+	}
+	model, ok := argValue(captured, "--model")
+	if !ok || model != "claude-opus-4.1" {
+		t.Fatalf("the fresh child was launched with --model %q (present=%t), want the parent's", model, ok)
+	}
+}

internal/tools/local_browser.go

@@ -548,11 +548,11 @@ func browserActionArgs(args map[string]any) (string, []string, error) {
 	if err != nil {
 		return "", nil, err
 	}
-	command = strings.ToLower(strings.TrimSpace(command))
-	spec, ok := browserActionSpecs[command]
+	command, ok := NormalizedBrowserActionCommand(command)
 	if !ok {
 		return "", nil, fmt.Errorf("command must be one of: %s", strings.Join(browserActionCommandNames(), ", "))
 	}
+	spec := browserActionSpecs[command]
 	values, err := stringArrayArg(args, "args")
 	if err != nil {
 		return "", nil, err
@@ -570,6 +570,16 @@ func browserActionArgs(args map[string]any) (string, []string, error) {
 	return command, commandArgs, nil
 }
 
+// NormalizedBrowserActionCommand returns the exact action that browser_action
+// will execute after normalizing its command argument. ACP uses it only for a
+// permission title, so an unrecognised command is never reflected as text that
+// the tool would reject.
+func NormalizedBrowserActionCommand(command string) (string, bool) {
+	command = strings.ToLower(strings.TrimSpace(command))
+	_, ok := browserActionSpecs[command]
+	return command, ok
+}
+
 func browserActionCommandArgs(command string, spec browserActionSpec, values []string) ([]string, error) {
 	switch command {
 	case "connect":
@@ -657,6 +667,13 @@ func browserOpenURLArg(args map[string]any) (string, error) {
 	if err != nil {
 		return "", err
 	}
+	return NormalizeBrowserOpenURL(rawURL)
+}
+
+// NormalizeBrowserOpenURL applies the browser_open URL rules before execution.
+// Keeping this exported within the internal package lets permission displays
+// describe the same destination the browser helper will open.
+func NormalizeBrowserOpenURL(rawURL string) (string, error) {
 	normalized := strings.TrimSpace(rawURL)
 	if !strings.Contains(normalized, "://") {
 		normalized = "https://" + normalized

internal/tools/web_fetch.go

@@ -13,6 +13,7 @@ import (
 	"strings"
 	"time"
 
+	"github.com/Gitlawb/zero/internal/proxydial"
 	"github.com/Gitlawb/zero/internal/redaction"
 	zeroSandbox "github.com/Gitlawb/zero/internal/sandbox"
 )
@@ -308,19 +309,48 @@ func webFetchSafeTransport(roundTripper http.RoundTripper, resolver webFetchReso
 		transport = http.DefaultTransport.(*http.Transport).Clone()
 	case *http.Transport:
 		transport = typed.Clone()
+	case *proxydial.Transport:
+		// Already guarded: rebuild from the inner transport so a second pass
+		// installs one dialer rather than nesting wrappers.
+		transport = typed.Transport.Clone()
 	default:
 		return roundTripper
 	}
 
 	dialer := &net.Dialer{Timeout: webFetchTimeout, KeepAlive: 30 * time.Second}
-	transport.Proxy = nil
+	// THE PROXY IS HONOURED, AND THAT IS A DELIBERATE REVERSAL. The original
+	// guarded fetch set Proxy to nil as part of tightening the SSRF guardrails,
+	// and the reasoning was sound as far as it went: a proxied request is dialed
+	// to the proxy, so the dial-time address pin below never sees the target and
+	// the DNS-rebind protection it provides does not apply. What that traded away
+	// was every fetch on a machine that reaches the network only through a
+	// configured proxy, which fails outright rather than degrades (#569).
+	//
+	// The target is still validated before the request is made, lexically and
+	// through the resolver, with the same block list the dialer applies. What a
+	// forward proxy removes is only the re-check at dial time, and that is
+	// inherent to using any forward proxy; a user who sets HTTPS_PROXY has chosen
+	// it.
+	//
+	// The returned round tripper is wrapped so the dialer learns which route
+	// the transport chose for each request: the one dial it lets past the guard
+	// is the one this transport opens to the proxy it picked for that request.
+	transport.Proxy = http.ProxyFromEnvironment
 	transport.DialContext = webFetchSafeDialContext(resolver, dialer)
 	transport.DialTLSContext = nil
-	return transport
+	return proxydial.Wrap(transport)
 }
 
 func webFetchSafeDialContext(resolver webFetchResolver, dialer webFetchDialer) func(context.Context, string, string) (net.Conn, error) {
 	return func(ctx context.Context, network string, address string) (net.Conn, error) {
+		// The proxy is not the target. See webFetchSafeTransport for why the
+		// proxy is honoured at all; here, the dial the transport opens to the
+		// proxy it selected for this request skips the pin, and nothing else
+		// does. A direct dial is pinned as it always was, including one whose
+		// address happens to equal a configured proxy endpoint.
+		if proxydial.IsProxyDial(ctx) {
+			return dialer.DialContext(ctx, network, address)
+		}
 		pinnedAddress, err := webFetchSafeDialAddress(ctx, resolver, address)
 		if err != nil {
 			return nil, err

internal/tools/web_fetch_proxy_test.go

@@ -0,0 +1,163 @@
+package tools
+
+import (
+	"context"
+	"errors"
+	"net"
+	"net/http"
+	"net/netip"
+	"net/url"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/Gitlawb/zero/internal/proxydial"
+)
+
+// webFetchTransportWithProxy builds the guarded web_fetch round tripper and
+// swaps in a proxy function, which is how the transport learns its route. The
+// environment is left alone deliberately: http.ProxyFromEnvironment reads it
+// once per process, so an environment-driven test would depend on test order.
+func webFetchTransportWithProxy(t *testing.T, resolver webFetchResolver, proxyFor func(*http.Request) (*url.URL, error)) *proxydial.Transport {
+	t.Helper()
+	roundTripper := webFetchSafeTransport(nil, resolver)
+	wrapped, ok := roundTripper.(*proxydial.Transport)
+	if !ok {
+		t.Fatalf("transport = %T, want the route-recording wrapper; without it no dial can be recognised as the proxy dial", roundTripper)
+	}
+	wrapped.Proxy = proxyFor
+	return wrapped
+}
+
+// THE PROXY IS NOT THE TARGET. With HTTPS_PROXY pointing at a local forward
+// proxy, the transport dials the proxy and tunnels the request through it. The
+// dialer used to refuse that dial as a loopback address, so every fetch on a
+// machine behind such a proxy failed with "loopback hosts are blocked" for a
+// public target that had already been validated (#569).
+func TestWebFetchTunnelsThroughTheConfiguredProxy(t *testing.T) {
+	listener, err := net.Listen("tcp", "127.0.0.1:0")
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer listener.Close()
+	arrived := make(chan string, 1)
+	go func() {
+		conn, err := listener.Accept()
+		if err != nil {
+			return
+		}
+		defer conn.Close()
+		buffer := make([]byte, 256)
+		n, _ := conn.Read(buffer)
+		arrived <- string(buffer[:n])
+	}()
+	proxyURL, err := url.Parse("http://" + listener.Addr().String())
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	// A proxied fetch never resolves the target on this side; the CONNECT
+	// carries the hostname and the proxy resolves it.
+	transport := webFetchTransportWithProxy(t,
+		webFetchResolverFunc(func(context.Context, string, string) ([]netip.Addr, error) {
+			return nil, errors.New("resolver must not be called for a proxied fetch")
+		}),
+		func(*http.Request) (*url.URL, error) { return proxyURL, nil })
+	client := &http.Client{Transport: transport, Timeout: 3 * time.Second}
+
+	_, err = client.Get("https://public.example/resource")
+	select {
+	case first := <-arrived:
+		if line := strings.SplitN(first, "\r\n", 2)[0]; line != "CONNECT public.example:443 HTTP/1.1" {
+			t.Fatalf("proxy received %q, want a CONNECT for the target", line)
+		}
+	case <-time.After(5 * time.Second):
+		t.Fatalf("the proxy never received a connection; request error: %v", err)
+	}
+}
+
+// AND A DIRECT FETCH STAYS PINNED, EVEN WHEN ITS ORIGIN IS THE PROXY'S OWN
+// ADDRESS.
+//
+// This is the NO_PROXY shape: the proxy function sends one host direct. An
+// exemption derived from asking that function about a request of our own
+// invention would answer "proxied" for the excluded host too, and this dial
+// would skip the pin and reach whatever the name resolves to at connect time.
+func TestWebFetchDirectRequestToTheProxyEndpointIsStillPinned(t *testing.T) {
+	proxyURL, err := url.Parse("http://rebind.example:80")
+	if err != nil {
+		t.Fatal(err)
+	}
+	lookups := 0
+	transport := webFetchTransportWithProxy(t,
+		webFetchResolverFunc(func(_ context.Context, _ string, host string) ([]netip.Addr, error) {
+			lookups++
+			return []netip.Addr{netip.MustParseAddr("127.0.0.1")}, nil
+		}),
+		func(request *http.Request) (*url.URL, error) {
+			if request.URL.Hostname() == "rebind.example" {
+				return nil, nil
+			}
+			return proxyURL, nil
+		})
+	client := &http.Client{Transport: transport, Timeout: 3 * time.Second}
+
+	_, err = client.Get("http://rebind.example/data")
+
+	if lookups == 0 {
+		t.Fatal("the direct dial skipped the address pin because its address matched the configured proxy endpoint")
+	}
+	if err == nil || !strings.Contains(err.Error(), "loopback hosts are blocked") {
+		t.Fatalf("err = %v, want the private answer to be refused", err)
+	}
+}
+
+// A proxy configured with a Unicode hostname is dialed by its IDNA-encoded
+// name, and it is still the proxy.
+func TestWebFetchUnicodeProxyHostnameIsStillTheProxy(t *testing.T) {
+	dialed := ""
+	transport := webFetchTransportWithProxy(t,
+		webFetchResolverFunc(func(context.Context, string, string) ([]netip.Addr, error) {
+			return nil, errors.New("resolver must not be called for a proxied fetch")
+		}),
+		func(*http.Request) (*url.URL, error) { return url.Parse("http://büro.example:3067") })
+	guarded := transport.DialContext
+	transport.DialContext = func(ctx context.Context, network, address string) (net.Conn, error) {
+		dialed = address
+		return guarded(ctx, network, address)
+	}
+	client := &http.Client{Transport: transport, Timeout: 3 * time.Second}
+
+	_, err := client.Get("https://public.example/resource")
+
+	if dialed != "xn--bro-hoa.example:3067" {
+		t.Fatalf("SETUP INVALID: dialed %q, want the IDNA-encoded proxy endpoint", dialed)
+	}
+	if err != nil && strings.Contains(err.Error(), "hosts are blocked") {
+		t.Fatalf("the configured proxy was refused by the guard: %v", err)
+	}
+}
+
+// Without a proxy the guard is exactly what it was: loopback is refused and
+// the dialer never runs.
+func TestWebFetchSafeDialStillRefusesLoopbackWithoutAProxy(t *testing.T) {
+	dialCalled := false
+	dial := webFetchSafeDialContext(
+		webFetchResolverFunc(func(_ context.Context, network string, host string) ([]netip.Addr, error) {
+			t.Fatalf("resolver consulted for a loopback literal: network=%q host=%q", network, host)
+			return nil, nil
+		}),
+		webFetchDialFunc(func(context.Context, string, string) (net.Conn, error) {
+			dialCalled = true
+			return nil, errors.New("dial should not run")
+		}),
+	)
+
+	_, err := dial(context.Background(), "tcp", "127.0.0.1:3067")
+	if err == nil || !strings.Contains(err.Error(), "loopback hosts are blocked") {
+		t.Fatalf("expected loopback rejection, got %v", err)
+	}
+	if dialCalled {
+		t.Fatal("loopback was dialed with no proxy configured")
+	}
+}

internal/tools/web_fetch_test.go

@@ -11,6 +11,7 @@ import (
 	"strings"
 	"testing"
 
+	"github.com/Gitlawb/zero/internal/proxydial"
 	zeroSandbox "github.com/Gitlawb/zero/internal/sandbox"
 )
 
@@ -325,15 +326,26 @@ func TestWebFetchToolConfiguresDialTimeSafetyForDefaultTransport(t *testing.T) {
 	}
 
 	client := tool.clientForRun()
-	transport, ok := client.Transport.(*http.Transport)
+	// The round tripper is the route-recording wrapper, not the bare transport:
+	// it is what tells the dialer which dial is the one to the proxy the
+	// transport picked for a given request. The guarded transport it wraps
+	// stays reachable, and is what the rest of this test inspects.
+	transport, ok := client.Transport.(*proxydial.Transport)
 	if !ok {
-		t.Fatalf("client transport = %T, want *http.Transport", client.Transport)
+		t.Fatalf("client transport = %T, want *proxydial.Transport", client.Transport)
 	}
 	if transport.DialContext == nil {
 		t.Fatal("expected web_fetch transport to install a safe DialContext")
 	}
-	if transport.Proxy != nil {
-		t.Fatal("expected web_fetch transport to disable proxy resolution")
+	// REVERSED ON PURPOSE. The guarded fetch used to pin Proxy to nil as part of
+	// the SSRF hardening, and this assertion held it there. #569 is what that
+	// cost: on a machine that reaches the network only through a configured
+	// forward proxy, every fetch failed outright. The proxy is honoured now, and
+	// the wrapper hands the dialer the route chosen for each request so the one
+	// dial it lets past the guard is the one to that proxy. The target is still
+	// validated before the request, which the tests below pin.
+	if transport.Proxy == nil {
+		t.Fatal("expected web_fetch transport to honour the environment proxy; a machine behind a forward proxy cannot fetch at all without it (#569)")
 	}
 }
 

internal/tui/commands.go

@@ -109,7 +109,7 @@ var commandDefinitions = []commandDefinition{
 		name:        "/voice",
 		usage:       "/voice",
 		group:       commandGroupRuntime,
-		description: "Toggle voice mode (hold Space to dictate).",
+		description: "Toggle voice mode (" + voiceCaptureUsage + ").",
 		kind:        commandVoice,
 	},
 	{

internal/tui/dictation.go

@@ -88,7 +88,7 @@ type dictationController struct {
 	waveBars []int
 	waveTick int
 
-	// voiceModeEnabled repurposes Space into hold-to-record (§13.9).
+	// voiceModeEnabled repurposes Ctrl+Space into hold-to-record (§13.9).
 	voiceModeEnabled bool
 	// eventTypesSupported records whether the terminal confirmed key-release
 	// reporting (Kitty protocol); eventTypesKnown gates it until the terminal has
@@ -173,7 +173,7 @@ func firstNonEmptyStr(a, b string) string {
 func (d dictationController) active() bool { return d.phase != dictIdle }
 
 // toggleDictation starts a recording when idle and stops-and-transcribes when
-// recording. Invoked by the voice-mode Space gesture; a call during
+// recording. Invoked by the voice-mode Ctrl+Space gesture; a call during
 // startup/transcription is ignored (the machine is mid-transition).
 func (m model) toggleDictation() (model, tea.Cmd) {
 	if !m.dictation.available() {
@@ -193,15 +193,15 @@ func (m model) toggleDictation() (model, tea.Cmd) {
 	}
 }
 
-// toggleVoiceMode flips the /voice hold-to-record gesture — the dictation
-// trigger. While on, Space records; run /voice again to type spaces normally.
+// toggleVoiceMode flips the /voice hold-to-record gesture. While on,
+// Ctrl+Space records and ordinary Space continues to type normally.
 func (m model) toggleVoiceMode() (model, tea.Cmd) {
 	if !m.dictation.available() {
 		return m.appendSystemNotice("Dictation is not configured. See docs/dictation.md to set up a local engine or a Groq/OpenAI key."), nil
 	}
 	m.dictation.voiceModeEnabled = !m.dictation.voiceModeEnabled
 	if m.dictation.voiceModeEnabled {
-		return m.showTransientNoticeInline("Voice mode on — hold Space to dictate; run /voice again to turn it off.", transientNoticeSuccess), nil
+		return m.showTransientNoticeInline("Voice mode on — "+voiceCaptureUsage+". Run /voice again to turn it off.", transientNoticeSuccess), nil
 	}
 	// Turning voice off is the "done dictating" signal, so release the warm sherpa
 	// streaming server — otherwise a loaded model keeps idling in RAM (and holding
@@ -374,7 +374,7 @@ func (m model) handleDictationStarted(msg dictationStartedMsg) (model, tea.Cmd)
 	if m.dictation.phase == dictStarting {
 		m.dictation.phase = dictRecording
 	}
-	// A voice-mode Space release that arrived mid-startup asked us to stop as soon
+	// A voice-mode Ctrl+Space release that arrived mid-startup asked us to stop as soon
 	// as recording began.
 	if m.dictation.voiceStopPending && m.dictation.phase == dictRecording {
 		m.dictation.voiceStopPending = false
@@ -480,12 +480,8 @@ func needsLeadingSpace(state composerState) bool {
 func (m model) dictationStatusChip() string {
 	switch m.dictation.phase {
 	case dictStarting, dictRecording:
-		stop := "release Space to stop"
-		if !m.dictation.eventTypesSupported {
-			stop = "press Space to stop" // press-to-toggle fallback
-		}
 		wave := zeroTheme.amber.Render("● " + renderWaveBars(m.dictation.waveBars) + " REC")
-		return wave + zeroTheme.muted.Render(" · "+stop+", Esc to cancel")
+		return wave + zeroTheme.muted.Render(" · "+m.voiceCaptureStatus()+", Esc to cancel")
 	case dictTranscribing:
 		return zeroTheme.accent.Render("●") + " " + zeroTheme.muted.Render("transcribing…")
 	}
@@ -601,13 +597,12 @@ func (m model) handleRecTick() (model, tea.Cmd) {
 	return m, nil
 }
 
-// voiceModeIndicator renders the persistent "voice mode on" hint shown while
-// idle so the user knows Space is repurposed to hold-to-record (§10).
+// voiceModeIndicator renders the current voice gesture or transcription state.
 func (m model) voiceModeIndicator() string {
 	if !m.dictation.voiceModeEnabled {
 		return ""
 	}
-	return zeroTheme.accent.Render("🎙 voice") + zeroTheme.muted.Render(" · "+m.dictation.currentModelLabel())
+	return zeroTheme.accent.Render("🎙 voice") + zeroTheme.muted.Render(" · "+m.voiceCaptureStatus()+" · "+m.dictation.currentModelLabel())
 }
 
 // dictationErrorText renders a dictation error for the transcript: a missing-

internal/tui/dictation_voice.go

@@ -4,17 +4,19 @@ import (
 	tea "charm.land/bubbletea/v2"
 )
 
-// Voice mode's Space-hold gesture — the (only) dictation trigger. Two terminal
+const voiceCaptureUsage = "hold Ctrl+Space to record; press it to toggle where key releases are unavailable"
+
+// Voice mode's Ctrl+Space gesture — the (only) dictation trigger. Two terminal
 // tiers:
 //
 //  1. The terminal confirms key-release reporting (Ghostty/Kitty/WezTerm, …):
-//     Space press starts recording, Space release stops it — true hold-to-record,
-//     no ambiguity.
-//  2. The terminal does not confirm release events: Space falls back to
+//     Ctrl+Space press starts recording and release stops it — true
+//     hold-to-record, with ordinary Space left available for typing.
+//  2. The terminal does not confirm release events: Ctrl+Space falls back to
 //     press-to-toggle (press to start, press again to stop) — a deliberately
 //     simpler, robust fallback than inferring release from key-repeat timing
-//     (racy in a terminal). This works on ANY terminal, so voice mode is always
-//     usable once enabled.
+//     (racy in a terminal). Legacy NUL input is decoded as Ctrl+Space by the
+//     terminal input layer, so the same matcher covers both tiers.
 //
 // Only active while voice mode is on; the rest of dispatch is built on
 // KeyPressMsg and is untouched.
@@ -27,8 +29,37 @@ func (m model) handleKeyboardEnhancements(msg tea.KeyboardEnhancementsMsg) model
 	return m
 }
 
-// handleVoiceSpacePress handles a Space press while voice mode is on.
-func (m model) handleVoiceSpacePress(msg tea.KeyMsg) (model, tea.Cmd) {
+func voiceCaptureKey(msg tea.KeyMsg) bool {
+	mod := msg.Key().Mod &^ (tea.ModCapsLock | tea.ModNumLock)
+	return keyIs(msg, tea.KeySpace) && mod == tea.ModCtrl
+}
+
+// voiceCaptureReleaseKey matches either half of the held Ctrl+Space chord. A
+// terminal may report Ctrl releasing first, or report the later Space release
+// without ModCtrl because Ctrl is no longer down.
+func voiceCaptureReleaseKey(msg tea.KeyMsg) bool {
+	return keyIs(msg, tea.KeySpace) || keyIs(msg, tea.KeyLeftCtrl) || keyIs(msg, tea.KeyRightCtrl)
+}
+
+func (m model) voiceCaptureStatus() string {
+	switch m.dictation.phase {
+	case dictStarting, dictRecording:
+		if m.dictation.eventTypesSupported {
+			return "release Ctrl+Space to stop"
+		}
+		return "press Ctrl+Space to stop"
+	case dictTranscribing:
+		return "transcribing…"
+	default:
+		if m.dictation.eventTypesSupported {
+			return "hold Ctrl+Space to record"
+		}
+		return "press Ctrl+Space to record"
+	}
+}
+
+// handleVoiceCapturePress handles Ctrl+Space while voice mode is on.
+func (m model) handleVoiceCapturePress(msg tea.KeyMsg) (model, tea.Cmd) {
 	if !m.dictation.eventTypesSupported {
 		// Tier 2: no release events — press-to-toggle.
 		return m.toggleDictation()
@@ -45,8 +76,8 @@ func (m model) handleVoiceSpacePress(msg tea.KeyMsg) (model, tea.Cmd) {
 	return m, nil // already recording; the release will stop it
 }
 
-// handleVoiceSpaceRelease stops a hold-to-record session when Space is released.
-func (m model) handleVoiceSpaceRelease() (model, tea.Cmd) {
+// handleVoiceCaptureRelease stops a hold-to-record session when Ctrl+Space is released.
+func (m model) handleVoiceCaptureRelease() (model, tea.Cmd) {
 	if !m.dictation.spaceHeld {
 		return m, nil
 	}

internal/tui/dictation_voice_test.go

@@ -2,6 +2,7 @@ package tui
 
 import (
 	"context"
+	"strings"
 	"testing"
 
 	tea "charm.land/bubbletea/v2"
@@ -36,7 +37,7 @@ func TestToggleVoiceModeFlips(t *testing.T) {
 	if !next.dictation.voiceModeEnabled {
 		t.Fatal("first /voice should enable voice mode")
 	}
-	if next.transientNotice.text != "Voice mode on — hold Space to dictate; run /voice again to turn it off." {
+	if next.transientNotice.text != "Voice mode on — hold Ctrl+Space to record; press it to toggle where key releases are unavailable. Run /voice again to turn it off." {
 		t.Errorf("voice-mode-on notice = %q", next.transientNotice.text)
 	}
 	if transcriptHasText(next, "Voice mode on") {
@@ -68,15 +69,27 @@ func TestKeyboardEnhancementsRecorded(t *testing.T) {
 	}
 }
 
-func TestVoiceSpaceHoldStartsRecording(t *testing.T) {
+func TestVoiceCaptureKeyIgnoresLockModifiers(t *testing.T) {
+	for _, mod := range []tea.KeyMod{
+		tea.ModCtrl | tea.ModCapsLock,
+		tea.ModCtrl | tea.ModNumLock,
+		tea.ModCtrl | tea.ModCapsLock | tea.ModNumLock,
+	} {
+		if !voiceCaptureKey(tea.KeyPressMsg(tea.Key{Code: tea.KeySpace, Mod: mod})) {
+			t.Fatalf("Ctrl+Space with lock modifiers %v was not recognized", mod)
+		}
+	}
+}
+
+func TestVoiceCaptureHoldStartsRecording(t *testing.T) {
 	m := model{dictation: batchOnlyController()}
 	m.dictation.voiceModeEnabled = true
 	m.dictation.eventTypesSupported = true
 
-	press := tea.KeyPressMsg(tea.Key{Code: tea.KeySpace})
-	next, cmd := m.handleVoiceSpacePress(press)
+	press := tea.KeyPressMsg(tea.Key{Code: tea.KeySpace, Mod: tea.ModCtrl})
+	next, cmd := m.handleVoiceCapturePress(press)
 	if next.dictation.phase != dictStarting {
-		t.Fatalf("Space press should start recording (phase=%d)", next.dictation.phase)
+		t.Fatalf("Ctrl+Space press should start recording (phase=%d)", next.dictation.phase)
 	}
 	if !next.dictation.spaceHeld {
 		t.Error("spaceHeld should be set in hold mode")
@@ -86,28 +99,28 @@ func TestVoiceSpaceHoldStartsRecording(t *testing.T) {
 	}
 }
 
-func TestVoiceSpaceHoldIgnoresRepeat(t *testing.T) {
+func TestVoiceCaptureHoldIgnoresRepeat(t *testing.T) {
 	m := model{dictation: batchOnlyController()}
 	m.dictation.voiceModeEnabled = true
 	m.dictation.eventTypesSupported = true
 	m.dictation.phase = dictRecording
 	m.dictation.spaceHeld = true
 
-	repeat := tea.KeyPressMsg(tea.Key{Code: tea.KeySpace, IsRepeat: true})
-	next, _ := m.handleVoiceSpacePress(repeat)
+	repeat := tea.KeyPressMsg(tea.Key{Code: tea.KeySpace, Mod: tea.ModCtrl, IsRepeat: true})
+	next, _ := m.handleVoiceCapturePress(repeat)
 	if next.dictation.phase != dictRecording {
 		t.Error("auto-repeat while held must not restart or change phase")
 	}
 }
 
-func TestVoiceSpaceReleaseStops(t *testing.T) {
+func TestVoiceCaptureReleaseStops(t *testing.T) {
 	m := model{dictation: batchOnlyController()}
 	m.dictation.voiceModeEnabled = true
 	m.dictation.eventTypesSupported = true
 	m.dictation.phase = dictRecording
 	m.dictation.spaceHeld = true
 
-	next, _ := m.handleVoiceSpaceRelease()
+	next, _ := m.handleVoiceCaptureRelease()
 	if next.dictation.phase != dictTranscribing {
 		t.Errorf("release should stop recording → transcribing (phase=%d)", next.dictation.phase)
 	}
@@ -123,7 +136,7 @@ func TestVoiceReleaseDuringStartupDefersStop(t *testing.T) {
 	m.dictation.phase = dictStarting
 	m.dictation.spaceHeld = true
 
-	next, _ := m.handleVoiceSpaceRelease()
+	next, _ := m.handleVoiceCaptureRelease()
 	if !next.dictation.voiceStopPending {
 		t.Error("a release during startup should defer the stop")
 	}
@@ -134,14 +147,186 @@ func TestVoiceReleaseDuringStartupDefersStop(t *testing.T) {
 	}
 }
 
-func TestVoiceSpaceToggleFallback(t *testing.T) {
+func TestVoiceCaptureToggleFallback(t *testing.T) {
 	m := model{dictation: batchOnlyController()}
 	m.dictation.voiceModeEnabled = true
 	m.dictation.eventTypesSupported = false // no release events → toggle fallback
 
-	press := tea.KeyPressMsg(tea.Key{Code: tea.KeySpace})
-	next, _ := m.handleVoiceSpacePress(press)
+	press := tea.KeyPressMsg(tea.Key{Code: tea.KeySpace, Mod: tea.ModCtrl})
+	next, _ := m.handleVoiceCapturePress(press)
 	if next.dictation.phase != dictStarting {
-		t.Errorf("toggle-mode Space should start recording (phase=%d)", next.dictation.phase)
+		t.Errorf("toggle-mode Ctrl+Space should start recording (phase=%d)", next.dictation.phase)
+	}
+}
+
+func TestVoiceModeCtrlSpaceReleaseStopsHoldRecording(t *testing.T) {
+	m := newModel(t.Context(), Options{})
+	m.dictation = batchOnlyController()
+	m.dictation.voiceModeEnabled = true
+	m.dictation.eventTypesSupported = true
+	m.dictation.phase = dictRecording
+	m.dictation.spaceHeld = true
+
+	updated, _ := m.Update(tea.KeyReleaseMsg(tea.Key{Code: tea.KeySpace, Mod: tea.ModCtrl}))
+	next := updated.(model)
+	if next.dictation.phase != dictTranscribing || next.dictation.spaceHeld {
+		t.Fatalf("Ctrl+Space release did not stop hold recording: phase=%d held=%v", next.dictation.phase, next.dictation.spaceHeld)
+	}
+}
+
+func TestVoiceModeCaptureStopsWhenEitherChordKeyIsReleased(t *testing.T) {
+	for _, test := range []struct {
+		name string
+		key  tea.Key
+	}{
+		{name: "left Ctrl first", key: tea.Key{Code: tea.KeyLeftCtrl}},
+		{name: "right Ctrl first", key: tea.Key{Code: tea.KeyRightCtrl}},
+		{name: "Space after Ctrl", key: tea.Key{Code: tea.KeySpace}},
+	} {
+		t.Run(test.name, func(t *testing.T) {
+			m := newModel(t.Context(), Options{})
+			m.dictation = batchOnlyController()
+			m.dictation.voiceModeEnabled = true
+			m.dictation.eventTypesSupported = true
+			m.dictation.phase = dictRecording
+			m.dictation.spaceHeld = true
+
+			updated, _ := m.Update(tea.KeyReleaseMsg(test.key))
+			next := updated.(model)
+			if next.dictation.phase != dictTranscribing || next.dictation.spaceHeld {
+				t.Fatalf("release did not stop hold recording: phase=%d held=%v", next.dictation.phase, next.dictation.spaceHeld)
+			}
+		})
+	}
+}
+
+func TestVoiceModeIndicatorDescribesTierAndPhase(t *testing.T) {
+	for _, test := range []struct {
+		name          string
+		releaseEvents bool
+		phase         dictationPhase
+		spaceHeld     bool
+		want          string
+	}{
+		{name: "toggle idle", want: "press Ctrl+Space to record"},
+		{name: "hold idle", releaseEvents: true, want: "hold Ctrl+Space to record"},
+		{name: "toggle recording", phase: dictRecording, want: "press Ctrl+Space to stop"},
+		{name: "hold recording", releaseEvents: true, phase: dictRecording, spaceHeld: true, want: "release Ctrl+Space to stop"},
+		{name: "transcribing", phase: dictTranscribing, want: "transcribing"},
+	} {
+		t.Run(test.name, func(t *testing.T) {
+			m := model{dictation: batchOnlyController()}
+			m.dictation.voiceModeEnabled = true
+			m.dictation.eventTypesSupported = test.releaseEvents
+			m.dictation.phase = test.phase
+			m.dictation.spaceHeld = test.spaceHeld
+			if got := m.voiceModeIndicator(); !strings.Contains(strings.ToLower(got), strings.ToLower(test.want)) {
+				t.Fatalf("voice indicator = %q, want %q", got, test.want)
+			}
+		})
+	}
+}
+
+func TestDictationStatusChipUsesVoiceCaptureShortcut(t *testing.T) {
+	for _, test := range []struct {
+		name          string
+		releaseEvents bool
+		want          string
+	}{
+		{name: "toggle", want: "press Ctrl+Space to stop"},
+		{name: "hold", releaseEvents: true, want: "release Ctrl+Space to stop"},
+	} {
+		t.Run(test.name, func(t *testing.T) {
+			m := model{dictation: batchOnlyController()}
+			m.dictation.voiceModeEnabled = true
+			m.dictation.eventTypesSupported = test.releaseEvents
+			m.dictation.phase = dictRecording
+			if got := m.dictationStatusChip(); !strings.Contains(got, test.want) {
+				t.Fatalf("dictation status = %q, want %q", got, test.want)
+			}
+		})
+	}
+}
+
+func TestVoiceCommandDescriptionExplainsBothTerminalTiers(t *testing.T) {
+	for _, command := range commandDefinitions {
+		if command.kind == commandVoice {
+			for _, want := range []string{"hold Ctrl+Space", "press it to toggle", "key releases"} {
+				if !strings.Contains(command.description, want) {
+					t.Fatalf("voice command description = %q, want %q", command.description, want)
+				}
+			}
+			return
+		}
+	}
+	t.Fatal("voice command definition not found")
+}
+
+func TestVoiceModePlainSpaceTypesNormally(t *testing.T) {
+	for _, releaseEvents := range []bool{false, true} {
+		t.Run(map[bool]string{false: "toggle", true: "hold"}[releaseEvents], func(t *testing.T) {
+			m := newModel(t.Context(), Options{})
+			m.dictation = batchOnlyController()
+			m.dictation.voiceModeEnabled = true
+			m.dictation.eventTypesSupported = releaseEvents
+
+			updated, cmd := m.Update(tea.KeyPressMsg(tea.Key{Code: tea.KeySpace}))
+			next := updated.(model)
+			if got := next.composerValue(); got != " " {
+				t.Fatalf("plain Space composer = %q, want one space", got)
+			}
+			if next.dictation.phase != dictIdle || cmd != nil {
+				t.Fatalf("plain Space started dictation: phase=%d cmd=%v", next.dictation.phase, cmd != nil)
+			}
+		})
+	}
+}
+
+func TestVoiceModeCtrlSpaceStartsAcrossTerminalTiers(t *testing.T) {
+	for _, releaseEvents := range []bool{false, true} {
+		t.Run(map[bool]string{false: "toggle", true: "hold"}[releaseEvents], func(t *testing.T) {
+			m := newModel(t.Context(), Options{})
+			m.dictation = batchOnlyController()
+			m.dictation.voiceModeEnabled = true
+			m.dictation.eventTypesSupported = releaseEvents
+
+			updated, cmd := m.Update(tea.KeyPressMsg(tea.Key{Code: tea.KeySpace, Mod: tea.ModCtrl}))
+			next := updated.(model)
+			if next.dictation.phase != dictStarting || cmd == nil {
+				t.Fatalf("Ctrl+Space did not start dictation: phase=%d cmd=%v", next.dictation.phase, cmd != nil)
+			}
+			if got := next.composerValue(); got != "" {
+				t.Fatalf("Ctrl+Space typed into composer: %q", got)
+			}
+		})
+	}
+}
+
+func TestVoiceModeTypingPreservesSpacesAcrossTerminalTiers(t *testing.T) {
+	for _, releaseEvents := range []bool{false, true} {
+		t.Run(map[bool]string{false: "toggle", true: "hold"}[releaseEvents], func(t *testing.T) {
+			m := newModel(t.Context(), Options{})
+			m.dictation = batchOnlyController()
+			m.dictation.voiceModeEnabled = true
+			m.dictation.eventTypesSupported = releaseEvents
+			for _, key := range []tea.Key{
+				{Code: 'f', Text: "f"},
+				{Code: 'i', Text: "i"},
+				{Code: 'x', Text: "x"},
+				{Code: tea.KeySpace},
+				{Code: 't', Text: "t"},
+				{Code: 'h', Text: "h"},
+				{Code: 'e', Text: "e"},
+			} {
+				updated, _ := m.Update(tea.KeyPressMsg(key))
+				m = updated.(model)
+			}
+			if got := m.composerValue(); got != "fix the" {
+				t.Fatalf("composer = %q, want %q", got, "fix the")
+			}
+			if m.dictation.phase != dictIdle {
+				t.Fatalf("typing started dictation: phase=%d", m.dictation.phase)
+			}
+		})
 	}
 }

internal/tui/model.go

@@ -1539,10 +1539,10 @@ func (m model) updateModel(msg tea.Msg) (tea.Model, tea.Cmd) {
 	case tea.KeyboardEnhancementsMsg:
 		return m.handleKeyboardEnhancements(msg), nil
 	case tea.KeyReleaseMsg:
-		// Voice mode's hold-to-record ends on Space release; every other release
-		// event is ignored (dispatch elsewhere is press-based).
-		if m.dictation.voiceModeEnabled && keyIs(msg, tea.KeySpace) {
-			return m.handleVoiceSpaceRelease()
+		// Voice mode's hold-to-record ends on Ctrl+Space release; every other
+		// release event is ignored (dispatch elsewhere is press-based).
+		if m.dictation.voiceModeEnabled && voiceCaptureReleaseKey(msg) {
+			return m.handleVoiceCaptureRelease()
 		}
 		return m, nil
 	case tea.KeyPressMsg:
@@ -1676,11 +1676,10 @@ func (m model) updateModel(msg tea.Msg) (tea.Model, tea.Cmd) {
 				return m.appendSystemNotice(fmt.Sprintf("Mouse released — drag to select and copy text. Press %s again to re-enable mouse interaction (clicks, right-click paste).", mouseKey)), nil
 			}
 			return m.showTransientNoticeInline("Mouse interaction re-enabled.", transientNoticeSuccess), nil
-		case m.dictation.voiceModeEnabled && !m.transcriptDetailed && keyIs(msg, tea.KeySpace) && !keyHasMod(msg, tea.ModCtrl) && !keyAlt(msg) && m.noBlockingModal():
-			// Voice mode (/voice) repurposes Space into the record gesture — the only
-			// dictation trigger — so it must not also type a space. Turn voice mode
-			// off (/voice) to type normally.
-			return m.handleVoiceSpacePress(msg)
+		case m.dictation.voiceModeEnabled && !m.transcriptDetailed && voiceCaptureKey(msg) && m.noBlockingModal():
+			// Voice mode reserves Ctrl+Space for recording; ordinary Space continues
+			// through the composer path below.
+			return m.handleVoiceCapturePress(msg)
 		case keyIs(msg, tea.KeyEsc):
 			// Esc is heavily overloaded below (subchat exit, MCP cancel, ask-user,
 			// permission deny, wizard/picker/suggestions dismiss, ...) before ever

internal/tui/stt_key_prompt.go

@@ -123,7 +123,7 @@ func (m model) finalizeSTTModelFromKey(p *sttKeyPromptState, prefix string) (tea
 	if modelID != "" {
 		label += " " + modelID
 	}
-	return m.showTransientNoticeInline(prefix+"Dictation model: "+label+". Run /voice, then hold Space to dictate.", transientNoticeSuccess), nil
+	return m.showTransientNoticeInline(prefix+"Dictation model: "+label+". Run /voice; "+voiceCaptureUsage+".", transientNoticeSuccess), nil
 }
 
 // sttKeyPromptOverlay renders the API-key prompt as a centered modal, matching

internal/tui/stt_model_picker.go

@@ -226,7 +226,7 @@ func (m model) handleSTTModelSelection(value string) (model, string) {
 			// instead); this is the manual-setup path (e.g. Termux).
 			hint += " Set stt.localModelPath to a model directory (see docs/dictation.md)."
 		} else {
-			hint += " Run /voice, then hold Space to dictate."
+			hint += " Run /voice; " + voiceCaptureUsage + "."
 		}
 		return m, hint
 	}