Merge pull request #4778 from Aschenbath/fix/hook-respect-occupied-proxy-port

fix(hook): skip proxy autostart on occupied loopback ports

Author: aeppling

docs/guide/proxy/overview.md

@@ -80,9 +80,11 @@ The question is only asked when the daemon can actually run: the `rtk-proxy` bin
 
 #### What the SessionStart hook actually does
 
-It does **not** do the redirection — that is the `settings.json` entry above. The hook is a *keep-alive*: when a session whose `ANTHROPIC_BASE_URL` points at a loopback address finds nothing listening there, it runs `rtk llm-proxy start`.
+It does **not** do the redirection — that is the `settings.json` entry above. The hook is a *keep-alive*: when a session whose `ANTHROPIC_BASE_URL` points at a loopback address finds nothing listening there, it runs `rtk llm-proxy start`. For a `localhost` URL it checks both `127.0.0.1` and `[::1]`.
 
-It reports through `systemMessage`, which is user-visible and never enters model context — RTK spends no tokens configuring itself. Every failure path stays silent rather than disrupting the session.
+If a listener at that address does not identify as RTK at `/health`, the hook never starts a daemon over it. It warns when `env.ANTHROPIC_BASE_URL` in `settings.json` or `RTK_PROXY_BIND` names that address, because the listener could be another service taking the requests or a hung RTK daemon, and the hook cannot tell which. With neither set, the hook treats the listener as your own gateway and stays silent. After starting a daemon, the hook still verifies the RTK identity before reporting that it started successfully.
+
+It reports through `systemMessage`, which is user-visible and never enters model context — RTK spends no tokens configuring itself. A problem is at most a warning; the hook never disrupts the session.
 
 This route only exists on harnesses that *have* a SessionStart hook, which is why the next one matters.
 

src/hooks/init/mod.rs

@@ -897,7 +897,7 @@ fn report_pipeline_health() {
 /// config channel (settings.json `env`); everyone else keeps the manual
 /// export line from `rtk llm-proxy start --env`.
 /// The base URL the global settings point Claude Code at, if any.
-fn proxy_env_target() -> Option<String> {
+pub(super) fn proxy_env_target() -> Option<String> {
     let dir = resolve_claude_dir().ok()?;
     let content = fs::read_to_string(dir.join(SETTINGS_JSON)).ok()?;
     let root: serde_json::Value = from_json_str(strip_leading_bom(&content)).ok()?;