hx-cli 0.2.13__tar.gz → 0.2.15__tar.gz

{hx_cli-0.2.13 → hx_cli-0.2.15}/CHANGELOG.md

@@ -28,6 +28,74 @@ the project follows [semantic versioning](https://semver.org/).
 
 ---
 
+## [0.2.15] - 2026-10-04
+
+### Changed
+
+- `/login` and `hx auth login` list the accounts as OpenAI, Claude, OpenRouter, Devin. At the
+  `hx auth login` menu, Enter still picks OpenRouter.
+
+### Fixed
+
+- `/login claude-code` behind a network whose TLS inspection signs with a certificate not
+  valid for servers ("unsupported certificate purpose") now gives Claude Code's reason and
+  the fix: have the network fixed or exempted, or set `HX_SSL_NO_VERIFY=1` meanwhile. It
+  used to give the whole sign-in URL and no fix. Turns and HX's own requests that fail the
+  same way give the same advice, not "add the CA", which is trusted already.
+- A `HX_CA_BUNDLE`, `SSL_CERT_FILE` or `REQUESTS_CA_BUNDLE` that names a file holding no
+  certificates no longer crashes HX at startup. HX says so and verifies against the system
+  trust store, and does not hand the file to Claude Code.
+- A wrapped error notice no longer shows a bright green background under every line after
+  the first.
+
+---
+
+## [0.2.14] - 2026-10-04
+
+### Added
+
+- When the installed Claude Code is behind its current release - and so lists older Claude
+  models than your subscription can run - `/model` says so under the list, with the command
+  that updates it (`brew upgrade --cask claude-code` for a Homebrew install, otherwise
+  `claude update`). After updating, the next `/model` lists the new models; no
+  refresh needed.
+
+### Changed
+
+- The model catalogue is refreshed from inside the `/model` picker: press `ctrl+r`. The
+  list updates in place and keeps your filter and selection; the outcome, or why the refresh
+  failed, shows under the list. With no models at all, `/model` now opens anyway and says
+  so, so `ctrl+r` is there to fill it.
+
+### Removed
+
+- `/models refresh`. It sat one letter away from `/model` and did nothing without its one
+  argument; use `ctrl+r` in the `/model` picker.
+
+### Fixed
+
+- On the `claude-code` route, the context window is the one Claude Code reports, not a
+  200k guess: Opus 5.5 runs with 1M. Claude Code lists its models without their sizes, and
+  what it serves depends on the plan, so a model starts at the window it was measured
+  serving on every plan - 1M for Opus 5.5, Sonnet 5.5, Sonnet 5 and Opus 4.7, 200k
+  otherwise - until its first turn reports the real window and maximum output for your
+  account. From then on the context gauge, the compaction threshold, the `/model` picker
+  and later sessions all use it, and a catalogue refresh keeps it.
+- A model Claude Code lists at its long context - Fable 5.1 as `claude-fable-5-1[1m]` -
+  runs at it: `/model` offers `claude-code/claude-fable-5-1[1m]` at 1M, where HX used to
+  drop the `[1m]` and run the model at its standard context.
+- A turn refused because the model, or its 1M context, needs usage credits your Claude plan
+  has off no longer reads "usage limit is reached. It resets at ...": HX says what needs the
+  credits, where to turn them on, and which model runs without them. Once they are on, the
+  next turn runs.
+- After a catalogue refresh (`ctrl+r` in `/model`, or signing in), the session in progress
+  measures its context against the refreshed window, not the one it started with.
+- `/model anthropic` (or typing `anthropic` in the picker) lists the Claude models your Claude
+  Code subscription runs, first, ahead of the per-token OpenRouter ones; `openai` does the same
+  for Codex. Several words match in any order: `/model anthropic sonnet`.
+
+---
+
 ## [0.2.13] - 2026-10-04
 
 ### Added
@@ -833,7 +901,9 @@ First release, published to PyPI as [`hx-cli`](https://pypi.org/project/hx-cli/)
 - `/configure` and `hx auth` for the OpenRouter key, `hx upgrade` for
   self-update, and `install.sh` bootstrapping uv with a pinned Python.
 
-[Unreleased]: https://github.com/aletisunil/hx/compare/v0.2.13...HEAD
+[Unreleased]: https://github.com/aletisunil/hx/compare/v0.2.15...HEAD
+[0.2.15]: https://github.com/aletisunil/hx/compare/v0.2.14...v0.2.15
+[0.2.14]: https://github.com/aletisunil/hx/compare/v0.2.13...v0.2.14
 [0.2.13]: https://github.com/aletisunil/hx/compare/v0.2.12...v0.2.13
 [0.2.12]: https://github.com/aletisunil/hx/compare/v0.2.11...v0.2.12
 [0.2.11]: https://github.com/aletisunil/hx/compare/v0.2.10...v0.2.11

{hx_cli-0.2.13 → hx_cli-0.2.15}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: hx-cli
-Version: 0.2.13
+Version: 0.2.15
 Summary: HX - an agent harness for the terminal
 Project-URL: Homepage, https://hx.sunilaleti.dev
 Project-URL: Documentation, https://hx.sunilaleti.dev
@@ -156,7 +156,7 @@ reach it at all.
 
 **Which Codex models you get** is decided by your ChatGPT account, not by HX.
 Signing in fetches the account's own list from the Codex backend, and `/model`
-offers exactly that; `/models refresh` asks again. Entitlement is per model —
+offers exactly that; ctrl+r in `/model` asks again. Entitlement is per model -
 the same `plus` account can run `gpt-5.6-sol` and be refused `gpt-5.3-codex` —
 so a model the picker does not list is one the subscription does not cover.
 
@@ -218,7 +218,7 @@ you to sign in again. On a machine with no browser at all, a session token in
 `HX_DEVIN_API_KEY` or `DEVIN_API_KEY` is used when nothing is saved.
 
 Signing in fetches the account's own model list, and `/model` offers exactly
-that; `/models refresh` asks again. Devin publishes each reasoning depth as a
+that; ctrl+r in `/model` asks again. Devin publishes each reasoning depth as a
 model of its own - Claude Opus 5 High, Claude Opus 5 Max - and HX folds each
 family into one model, so `/effort` picks the depth on Devin exactly as it does
 on Codex. A fast lane or a 1M-context lane stays a separate model, since it
@@ -264,8 +264,15 @@ rest - are removed from its environment; its TLS settings are kept (see
 `claude` other than the one on `PATH`.
 
 `/model` offers the models Claude Code lists for the account, each with the
-efforts it accepts for `/effort`; `/models refresh` asks again. When a usage
-limit is reached, HX says which one and when it resets.
+efforts it accepts for `/effort`; ctrl+r in `/model` asks again. A model Claude
+Code runs at its long context keeps `[1m]` in its id
+(`claude-code/claude-fable-5-1[1m]`), exactly as Claude Code's own `/model` runs
+it. Claude Code lists no context sizes, so a model starts at the window it was
+measured serving on every plan - 1M for Opus 5.5, Sonnet 5.5, Sonnet 5 and Opus
+4.7, otherwise 200k - and from its first turn uses the window Claude Code
+reports for your account. When a usage limit is reached, HX says which one and
+when it resets; when a model or its 1M context needs usage credits your plan
+has off, HX says that instead, and what to pick without them.
 
 **Web search.** Optional, and the one credential that is not a model route.
 It powers two tools:
@@ -328,7 +335,13 @@ export HX_CA_BUNDLE=/path/to/corp-ca.pem   # SSL_CERT_FILE and REQUESTS_CA_BUNDL
 `HX_SSL_NO_VERIFY=1` turns verification off entirely; it prints a warning at
 startup every session, because it is not a fix. A TLS failure is reported in
 one line - `/model` and the startup notice both name the certificate problem
-rather than reporting an empty catalogue with no cause.
+rather than reporting an empty catalogue with no cause. A file that holds no
+certificates is ignored, with a startup notice that says so.
+
+"Unsupported certificate purpose" (or "unsuitable") is different: the CA is
+trusted, but the proxy signs with a certificate that is not valid for servers,
+so no CA setting fixes it. The network has to fix that certificate or exempt
+the service from inspection; until then only `HX_SSL_NO_VERIFY=1` gets through.
 
 The same settings cover the `claude-code` route, whose requests Claude Code
 makes with its own TLS stack: HX passes `HX_CA_BUNDLE` on to it as
@@ -421,7 +434,7 @@ be rebound (see [Keybindings](#keybindings)).
 | `ctrl+d` | exit, when the prompt is empty |
 | `shift+tab` | cycle permission mode |
 | `ctrl+p` | command palette |
-| `ctrl+l` | model picker |
+| `ctrl+l` | model picker; inside it, `ctrl+r` fetches the catalogue again |
 | `ctrl+o` | expand tool output (also `ctrl+r`) |
 | `ctrl+t` | show the current plan |
 | `ctrl+x` | copy the selected message to the clipboard |
@@ -527,8 +540,7 @@ silently resolved.
 
 | Command | Does |
 |---|---|
-| `/model [query]` | pick a model; shows context window, price per Mtok, cache support |
-| `/models refresh` | re-fetch the catalogue |
+| `/model [query]` | pick a model; shows context window, price per Mtok, cache support. `ctrl+r` in the picker re-fetches the catalogue |
 | `/effort [level]` | how hard a reasoning model thinks, from the levels it offers |
 | `/configure` | session settings and the API key |
 | `/login [provider]` | sign in to a model route |

{hx_cli-0.2.13 → hx_cli-0.2.15}/README.md

@@ -115,7 +115,7 @@ reach it at all.
 
 **Which Codex models you get** is decided by your ChatGPT account, not by HX.
 Signing in fetches the account's own list from the Codex backend, and `/model`
-offers exactly that; `/models refresh` asks again. Entitlement is per model —
+offers exactly that; ctrl+r in `/model` asks again. Entitlement is per model -
 the same `plus` account can run `gpt-5.6-sol` and be refused `gpt-5.3-codex` —
 so a model the picker does not list is one the subscription does not cover.
 
@@ -177,7 +177,7 @@ you to sign in again. On a machine with no browser at all, a session token in
 `HX_DEVIN_API_KEY` or `DEVIN_API_KEY` is used when nothing is saved.
 
 Signing in fetches the account's own model list, and `/model` offers exactly
-that; `/models refresh` asks again. Devin publishes each reasoning depth as a
+that; ctrl+r in `/model` asks again. Devin publishes each reasoning depth as a
 model of its own - Claude Opus 5 High, Claude Opus 5 Max - and HX folds each
 family into one model, so `/effort` picks the depth on Devin exactly as it does
 on Codex. A fast lane or a 1M-context lane stays a separate model, since it
@@ -223,8 +223,15 @@ rest - are removed from its environment; its TLS settings are kept (see
 `claude` other than the one on `PATH`.
 
 `/model` offers the models Claude Code lists for the account, each with the
-efforts it accepts for `/effort`; `/models refresh` asks again. When a usage
-limit is reached, HX says which one and when it resets.
+efforts it accepts for `/effort`; ctrl+r in `/model` asks again. A model Claude
+Code runs at its long context keeps `[1m]` in its id
+(`claude-code/claude-fable-5-1[1m]`), exactly as Claude Code's own `/model` runs
+it. Claude Code lists no context sizes, so a model starts at the window it was
+measured serving on every plan - 1M for Opus 5.5, Sonnet 5.5, Sonnet 5 and Opus
+4.7, otherwise 200k - and from its first turn uses the window Claude Code
+reports for your account. When a usage limit is reached, HX says which one and
+when it resets; when a model or its 1M context needs usage credits your plan
+has off, HX says that instead, and what to pick without them.
 
 **Web search.** Optional, and the one credential that is not a model route.
 It powers two tools:
@@ -287,7 +294,13 @@ export HX_CA_BUNDLE=/path/to/corp-ca.pem   # SSL_CERT_FILE and REQUESTS_CA_BUNDL
 `HX_SSL_NO_VERIFY=1` turns verification off entirely; it prints a warning at
 startup every session, because it is not a fix. A TLS failure is reported in
 one line - `/model` and the startup notice both name the certificate problem
-rather than reporting an empty catalogue with no cause.
+rather than reporting an empty catalogue with no cause. A file that holds no
+certificates is ignored, with a startup notice that says so.
+
+"Unsupported certificate purpose" (or "unsuitable") is different: the CA is
+trusted, but the proxy signs with a certificate that is not valid for servers,
+so no CA setting fixes it. The network has to fix that certificate or exempt
+the service from inspection; until then only `HX_SSL_NO_VERIFY=1` gets through.
 
 The same settings cover the `claude-code` route, whose requests Claude Code
 makes with its own TLS stack: HX passes `HX_CA_BUNDLE` on to it as
@@ -380,7 +393,7 @@ be rebound (see [Keybindings](#keybindings)).
 | `ctrl+d` | exit, when the prompt is empty |
 | `shift+tab` | cycle permission mode |
 | `ctrl+p` | command palette |
-| `ctrl+l` | model picker |
+| `ctrl+l` | model picker; inside it, `ctrl+r` fetches the catalogue again |
 | `ctrl+o` | expand tool output (also `ctrl+r`) |
 | `ctrl+t` | show the current plan |
 | `ctrl+x` | copy the selected message to the clipboard |
@@ -486,8 +499,7 @@ silently resolved.
 
 | Command | Does |
 |---|---|
-| `/model [query]` | pick a model; shows context window, price per Mtok, cache support |
-| `/models refresh` | re-fetch the catalogue |
+| `/model [query]` | pick a model; shows context window, price per Mtok, cache support. `ctrl+r` in the picker re-fetches the catalogue |
 | `/effort [level]` | how hard a reasoning model thinks, from the levels it offers |
 | `/configure` | session settings and the API key |
 | `/login [provider]` | sign in to a model route |

{hx_cli-0.2.13 → hx_cli-0.2.15}/src/hx/__init__.py

@@ -1,5 +1,5 @@
 """HX - an agent harness for the terminal."""
 
-__version__ = "0.2.13"
+__version__ = "0.2.15"
 
 __all__ = ["__version__"]

{hx_cli-0.2.13 → hx_cli-0.2.15}/src/hx/agents/subagent.py

@@ -173,6 +173,7 @@ class SubagentRunner:
             model_info=self.models.get_or_default(model) if self.models else None,
             project_context=self.project_context,
             hooks=self.hooks,
+            models=self.models,
         )
         loop.origin = f"{definition.name} subagent"
         return loop

{hx_cli-0.2.13 → hx_cli-0.2.15}/src/hx/auth/claude_code.py

@@ -290,6 +290,22 @@ def login_terminal() -> int:
 
 
 _URL = re.compile(r"https://\S+")
+_PASTE_PROMPT = re.compile(r"^.*Paste code[^>]*>\s*")
+_FAILED = re.compile(r"^Login failed:\s*", re.IGNORECASE)
+
+
+def _failure(output: list[str]) -> str | None:
+    """Why ``claude auth login`` failed: its last line of its own, ``unsupported
+    certificate purpose`` from ``Login failed: unsupported certificate purpose``.
+
+    Not the URL it printed before - the screen already showed that, and it is
+    wider than the notice - nor the paste prompt the reason is printed after.
+    """
+    for line in reversed(output):
+        line = _FAILED.sub("", _PASTE_PROMPT.sub("", line)).strip()
+        if line and not _URL.search(line):
+            return line
+    return None
 
 
 class LoginFailed(Exception):
@@ -361,8 +377,8 @@ async def login_interactive(interaction: LoginInteraction) -> LoginStatus:
     forget_status()
 
     if code != 0:
-        tail = " ".join(line.strip() for line in output[-3:] if line.strip())
-        raise LoginFailed(f"`claude auth login` failed: {tail or f'exit {code}'}")
+        reason = _failure(output) or f"exit {code}"
+        raise LoginFailed(net.with_tls_hint(f"`claude auth login` failed: {reason}"))
     current = await status_async(fresh=True)
     if current is None or not current.logged_in:
         raise LoginFailed("Claude Code still reports no login.")

{hx_cli-0.2.13 → hx_cli-0.2.15}/src/hx/cli.py

@@ -291,13 +291,10 @@ class Runtime:
             self.notices.append(f"Model catalogue refresh failed: {describe(exc)}")
             return
         finally:
-            # The loop resolved its model before the refresh, from the cache
-            # being replaced. Left alone it would gauge against yesterday's
-            # context window and decide image support from a cache that did
-            # not record it - until the user happened to switch models.
-            self.loop.model_info = self.models.get_or_default(self.loop.model)
+            self.loop.catalogue_refreshed()
         for label, error in self.models.subscription_errors():
             self.notices.append(f"Could not list this account's {label} models: {error}")
+        self.notices.extend(self.models.subscription_advice())
 
     async def aclose(self) -> None:
         if self.mcp is not None:
@@ -489,6 +486,7 @@ def build_runtime(parsed: ParsedArgs, *, resume: str | None = None) -> Runtime:
         project_context=project_context,
         instructions=instructions,
         hooks=hooks,
+        models=models,
     )
 
     return Runtime(
@@ -1303,6 +1301,8 @@ def _report_models_after_login(provider_id: str) -> None:
         print(f"Could not refresh the model list: {describe(exc)}", file=sys.stderr)
     for label, error in models.subscription_errors():
         print(f"Could not list this account's {label} models: {error}", file=sys.stderr)
+    for advice in models.subscription_advice():
+        print(advice, file=sys.stderr)
 
     available = [m.id for m in models.all() if m.provider_id == provider_id]
     if not available:
@@ -1432,8 +1432,10 @@ def _choose_provider() -> str:
     print("Sign in to:")
     for index, spec in enumerate(registry.SPECS, start=1):
         print(f"  {index}  {spec.label}")
+    # Enter still means OpenRouter, wherever it sits in the list.
+    default = str(next(i for i, s in enumerate(registry.SPECS, start=1) if s.id == OPENROUTER))
     try:
-        choice = input("Choice [1]: ").strip() or "1"
+        choice = input(f"Choice [{default}]: ").strip() or default
     except (EOFError, KeyboardInterrupt):
         print()
         return OPENROUTER

{hx_cli-0.2.13 → hx_cli-0.2.15}/src/hx/core/loop.py

@@ -66,7 +66,7 @@ if TYPE_CHECKING:
     from hx.hooks.engine import HookEngine
     from hx.permissions.engine import PermissionEngine
     from hx.providers.base import Provider
-    from hx.providers.models import ModelInfo
+    from hx.providers.models import ModelInfo, ModelRegistry
     from hx.skills.runtime import ActiveSkills
     from hx.tools.registry import ToolRegistry
 
@@ -107,6 +107,7 @@ class AgentLoop:
         project_context: str | None = None,
         instructions: list[Instructions] | None = None,
         hooks: HookEngine | None = None,
+        models: ModelRegistry | None = None,
     ) -> None:
         self.provider = provider
         self.session = session
@@ -124,6 +125,9 @@ class AgentLoop:
         self.instructions = instructions or []
         """The AGENTS.md files folded into ``project_context``, least specific first."""
         self.hooks = hooks
+        self.models = models
+        """Where a window the backend reports is kept, so the picker and the
+        next session start from it rather than from the catalogue's guess."""
         self._cancelled = False
         self._turn_index = 0
         self._steer: list[UserTurn] = []
@@ -155,6 +159,19 @@ class AgentLoop:
             self.compactor.provider = provider
         return previous
 
+    def catalogue_refreshed(self) -> None:
+        """Re-read the model in force from a catalogue that has just changed.
+
+        It was resolved from the one being replaced. Left alone, the window the
+        gauge and the compaction threshold measure against would stay the old
+        one, and image support would be decided from it, until the user
+        happened to switch models.
+        """
+        if self.models is None:
+            return
+        self.model_info = self.models.get_or_default(self.model)
+        self.session.usage.context_window = self.model_info.context_window
+
     def set_model(self, model_id: str, model_info: ModelInfo | None = None) -> None:
         self.session.meta.model = model_id
         self.model_info = model_info
@@ -450,6 +467,7 @@ class AgentLoop:
                 if isinstance(item, StreamEnd):
                     stop_reason = item.stop_reason
                     usage = item.usage
+                    self._adopt_limits(item)
                     continue
                 if not isinstance(item, StreamDelta):  # pragma: no cover - defensive
                     continue
@@ -581,6 +599,26 @@ class AgentLoop:
         blocks.extend(tool_calls)
         return assistant_message(blocks, model=self.model)
 
+    def _adopt_limits(self, end: StreamEnd) -> None:
+        """Take the window the backend reported over the catalogue's figure.
+
+        Before the usage update that follows, so the gauge it drives - and the
+        compaction threshold measured against the same window - move together.
+        Kept in the catalogue too, by every mode and every subagent alike: a
+        figure only the live session knew would be the guess again next time.
+        """
+        info = self.model_info
+        if info is None or info.id != self.model:
+            return
+        window = end.context_window or info.context_window
+        output = end.max_output_tokens or info.max_output_tokens
+        if (window, output) == (info.context_window, info.max_output_tokens):
+            return
+        self.model_info = replace(info, context_window=window, max_output_tokens=output)
+        self.session.usage.context_window = window
+        if self.models is not None:
+            self.models.adopt_limits(info.id, window, output)
+
     def _record_usage(
         self,
         usage: TurnUsage,

{hx_cli-0.2.13 → hx_cli-0.2.15}/src/hx/net.py

@@ -41,11 +41,38 @@ _TRUTHY = frozenset({"1", "true", "yes", "on"})
 
 
 def ca_bundle() -> Path | None:
-    """The CA bundle the environment names, if it points at a real file."""
+    """The CA bundle the environment names, if it points at a file of certificates."""
+    named = _named_bundle()
+    if named is None or _load_error(named[1]) is not None:
+        return None
+    return named[1]
+
+
+def _named_bundle() -> tuple[str, Path] | None:
+    """The first of :data:`CA_BUNDLE_VARS` that names a real file, and that file."""
     for name in CA_BUNDLE_VARS:
         raw = (os.environ.get(name) or "").strip()
         if raw and Path(raw).expanduser().is_file():
-            return Path(raw).expanduser()
+            return name, Path(raw).expanduser()
+    return None
+
+
+def _load_error(path: Path) -> str | None:
+    """Why ``path`` cannot serve as a CA bundle - a DER file, a key, an empty
+    file - or ``None`` when it can. Asked again only when the file changes."""
+    try:
+        stat = path.stat()
+    except OSError as exc:
+        return exc.strerror or str(exc)
+    return _load_error_of(path, stat.st_mtime_ns, stat.st_size)
+
+
+@lru_cache(maxsize=4)
+def _load_error_of(path: Path, mtime_ns: int, size: int) -> str | None:
+    try:
+        ssl.create_default_context(cafile=str(path))
+    except (ssl.SSLError, OSError, ValueError) as exc:
+        return _flatten(getattr(exc, "reason", None) or str(exc))
     return None
 
 
@@ -80,6 +107,15 @@ def tls_notice() -> str | None:
     """One line for the startup transcript when TLS is not stock."""
     if verification_disabled():
         return f"{NO_VERIFY_VAR} is set: TLS certificates are not being verified."
+    named = _named_bundle()
+    if named is not None and (error := _load_error(named[1])) is not None:
+        # Ignored, as OpenSSL and Node ignore a CA file they cannot read: failing
+        # to start would cost every route, the ones this file is not for too.
+        name, path = named
+        return (
+            f"{name} names {path}, which holds no usable CA certificates ({error}). "
+            f"Verifying TLS against the system trust store instead."
+        )
     bundle = ca_bundle()
     return f"Verifying TLS against {bundle}." if bundle is not None else None
 
@@ -108,13 +144,29 @@ _CERT_FAILURE = re.compile(
     r"certificate verif"
     r"|self[- ]signed certificate"
     r"|unable to (?:get local issuer|verify the first) certificate"
-    r"|UNABLE_TO_VERIFY_LEAF_SIGNATURE|UNABLE_TO_GET_ISSUER_CERT|SELF_SIGNED_CERT_IN_CHAIN",
+    r"|UNABLE_TO_VERIFY_LEAF_SIGNATURE|UNABLE_TO_GET_ISSUER_CERT|SELF_SIGNED_CERT_IN_CHAIN"
+    r"|certificate purpose|INVALID_PURPOSE",
     re.IGNORECASE,
 )
 
+_WRONG_PURPOSE = re.compile(r"(?:unsupported|unsuitable) certificate purpose|INVALID_PURPOSE")
+"""A chain the client does trust, but with a certificate in it - typically the
+issuing CA of a network that intercepts TLS - that may not serve as a TLS
+server's: OpenSSL says "unsuitable", the BoringSSL in Claude Code "unsupported"."""
+
 
-def tls_hint() -> str:
-    """What to do about a certificate the client would not trust."""
+def tls_hint(reason: str = "") -> str:
+    """What to do about a certificate the client would not accept.
+
+    ``reason`` is the client's own words, when there are any: a certificate of
+    the wrong purpose is already trusted, so adding its CA again changes nothing.
+    """
+    if _WRONG_PURPOSE.search(reason):
+        return (
+            "Your network intercepts TLS with a certificate that is not valid for servers. "
+            "Ask its administrator to fix that certificate or to exclude this service from "
+            f"inspection; until then, {NO_VERIFY_VAR}=1 turns verification off."
+        )
     bundle = ca_bundle()
     if bundle is not None:
         return (
@@ -130,7 +182,7 @@ def tls_hint() -> str:
 def with_tls_hint(message: str) -> str:
     """``message``, followed by :func:`tls_hint` when it reports a certificate
     failure - in any client's words: OpenSSL's, Node's, Claude Code's."""
-    hint = tls_hint()
+    hint = tls_hint(message)
     if not _CERT_FAILURE.search(message) or hint in message:
         return message
     return f"{message.rstrip().rstrip('.')}. {hint}"
@@ -156,7 +208,8 @@ def describe(exc: BaseException) -> str:
                 or getattr(err, "reason", None)
                 or "certificate verify failed"
             )
-            return f"TLS certificate verification failed ({_flatten(reason)}). {tls_hint()}"
+            reason = _flatten(reason)
+            return f"TLS certificate verification failed ({reason}). {tls_hint(reason)}"
         if isinstance(err, ssl.SSLError):
             return f"TLS handshake failed: {_flatten(err.reason or str(err))}."
     if isinstance(exc, httpx.TimeoutException):

{hx_cli-0.2.13 → hx_cli-0.2.15}/src/hx/providers/base.py

@@ -38,6 +38,11 @@ class StreamDelta:
 class StreamEnd:
     stop_reason: StopReason
     usage: TurnUsage = field(default_factory=TurnUsage)
+    context_window: int | None = None
+    """The model's window as the backend reported it running this turn, when
+    it does. Truer than the catalogue's figure, which for some routes is a
+    guess: Claude Code lists its models without their sizes."""
+    max_output_tokens: int | None = None
 
 
 StreamItem = StreamDelta | StreamEnd

{hx_cli-0.2.13 → hx_cli-0.2.15}/src/hx/providers/claude_code.py

@@ -51,6 +51,7 @@ from hx.core.usage import TurnUsage
 from hx.net import with_tls_hint
 from hx.providers import claude_code_transcript as transcript
 from hx.providers.base import ProviderError, ProviderRequest, StreamDelta, StreamEnd, StreamItem
+from hx.providers.claude_code_catalogue import DATED
 from hx.providers.claude_code_cli import CliProcess, Exit, ServedTool, ToolServer
 
 PROVIDER_ID = cc_auth.PROVIDER_ID
@@ -435,7 +436,7 @@ class ClaudeCodeProvider:
             frame = await frames.get()
             if isinstance(frame, Exit):
                 conversation.state = State.DEAD
-                raise ProviderError(_exit_message(frame, turn.rate_limit))
+                raise ProviderError(_exit_message(frame, turn.rate_limit, request.model))
             kind = frame.get("type")
             if kind == "stream_event" and frame.get("parent_tool_use_id") is None:
                 for item in turn.consume(frame.get("event") or {}):
@@ -465,7 +466,13 @@ class ClaudeCodeProvider:
                 payload = from_payload(turn)
                 if payload is not None:
                     yield payload
-                yield StreamEnd(turn.stop_reason(), turn.finish_usage(started))
+                window, output = _reported_limits(frame, request.model)
+                yield StreamEnd(
+                    turn.stop_reason(),
+                    turn.finish_usage(started),
+                    context_window=window,
+                    max_output_tokens=output,
+                )
                 return
 
     def _remember(self, conversation: Conversation, turn: _Turn) -> None:
@@ -800,6 +807,30 @@ def _wire_model(model_id: str) -> str:
     return model_id[len(MODEL_PREFIX) :] if model_id.startswith(MODEL_PREFIX) else model_id
 
 
+def _reported_limits(frame: dict[str, Any], model_id: str) -> tuple[int | None, int | None]:
+    """``(contextWindow, maxOutputTokens)`` Claude Code reports for the model run.
+
+    ``modelUsage`` is keyed by the resolved name, and lists every model the
+    turn touched - one Claude Code chose for itself among them - so only the
+    entry for the model asked for is taken. Started by alias (``opus``), that
+    entry cannot be told apart and nothing is taken.
+    """
+    wanted = _wire_model(model_id)
+    usage = frame.get("modelUsage")
+    for name, entry in usage.items() if isinstance(usage, dict) else ():
+        if not isinstance(entry, dict):
+            continue
+        names = {DATED.sub("", str(n)) for n in (name, entry.get("canonicalModel")) if n}
+        if wanted not in names:
+            continue
+        window, output = entry.get("contextWindow"), entry.get("maxOutputTokens")
+        return (
+            window if isinstance(window, int) and window > 0 else None,
+            output if isinstance(output, int) and output > 0 else None,
+        )
+    return None, None
+
+
 def _private_file(text: str) -> Path:
     fd, name = tempfile.mkstemp(prefix="hx-claude-", suffix=".md")
     with os.fdopen(fd, "w", encoding="utf-8") as handle:
@@ -833,7 +864,9 @@ def _startup_failure(message: str, cli: CliProcess) -> str:
     return with_tls_hint(f"Claude Code failed to start: {message}")
 
 
-def _exit_message(frame: Exit, rate_limit: dict[str, Any] | None) -> str:
+def _exit_message(frame: Exit, rate_limit: dict[str, Any] | None, model_id: str) -> str:
+    if _needs_credits(rate_limit, frame.stderr):
+        return _credits_message(model_id, frame.stderr.strip())
     if rate_limit:
         return _limit_message(rate_limit)
     detail = frame.stderr.strip()
@@ -849,6 +882,8 @@ def _result_error(
     errors = frame.get("errors")
     text = "; ".join(str(e) for e in errors) if isinstance(errors, list) and errors else ""
     text = text or str(frame.get("result") or frame.get("subtype") or "unknown error")
+    if _needs_credits(rate_limit, text):
+        return _credits_message(request.model, text)
     if _billed_as_extra_usage(frame, text, rate_limit):
         return _extra_usage_message(request, text)
     if rate_limit or "usage limit" in text.lower() or "out of extra usage" in text.lower():
@@ -858,6 +893,40 @@ def _result_error(
     return with_tls_hint(f"Claude Code: {text.strip()}")
 
 
+def _needs_credits(rate_limit: dict[str, Any] | None, text: str) -> bool:
+    """A turn refused because the model, or its long context, needs usage credits.
+
+    Claude Code reports it as a rejected rate limit, with the billing period's
+    reset beside it, but no usage window is reached: the plan does not include
+    what was asked for, and it fails the same way until credits are turned on.
+    """
+    if (rate_limit or {}).get("errorCode") == "credits_required":
+        return True
+    lowered = text.lower()
+    return "requires usage credits" in lowered or "usage credits required" in lowered
+
+
+def _credits_message(model_id: str, detail: str) -> str:
+    """Said in HX's words alone: Claude Code's own adds a link meant for its
+    CLI and advice for flags HX sets itself."""
+    model = _wire_model(model_id)
+    base = model.removesuffix("[1m]")
+    lowered = detail.lower()
+    # Asked for at 1M, it is the long context that needs them - unless what was
+    # said names the model itself: "Fable 5.1 requires usage credits".
+    names_model = "requires usage credits" in lowered
+    if "1m context" in lowered or "long context" in lowered or (model != base and not names_model):
+        what = f"The 1M context of {base} needs"
+        instead = f"pick {MODEL_PREFIX}{base} for its standard context"
+    else:
+        what = f"{base} needs"
+        instead = "pick another model"
+    return (
+        f"{what} usage credits, which your Claude plan has off - its usage limits are not "
+        f"reached. Turn them on at claude.ai/settings/usage and send again, or {instead}."
+    )
+
+
 def _billed_as_extra_usage(
     frame: dict[str, Any], text: str, rate_limit: dict[str, Any] | None
 ) -> bool: