claude-autorouter 0.3.4 → 0.3.5

package/.env.example

@@ -7,6 +7,10 @@ AUTOROUTER_EVALUATOR=jev
 AUTOROUTER_STATUSLINE=1
 # Optional metadata logs on stderr. Redirect stderr to a file when using the UI.
 # AUTOROUTER_DEBUG=1
+# Optional: allow two tool-free Stop-hook continuations, then end the turn on
+# the third block. Applies to /goal and all Stop/SubagentStop hooks.
+# Unset keeps Claude's default (currently 8); 0 DISABLES the cap.
+# CLAUDE_CODE_STOP_HOOK_BLOCK_CAP=2
 # Required for Jev only; subscription + Ollama needs no API keys.
 TYPESAFE_API_KEY=
 # For API billing instead, set AUTOROUTER_AUTH_MODE=api-key and fill this in.

package/README.md

@@ -104,5 +104,6 @@ Historical measurements before 0.3.2, on a 16 GiB M4: Tev1 0.8B matched 18/24 he
 - The selected evaluator receives bounded excerpts that can contain source code and tool results: TypeSafe with Jev, or the local service with Ollama. Jev also receives system-text excerpts; the local path excludes Claude's executor system instructions. Anthropic receives the complete request. Images, document payloads, and private thinking are omitted from classifier input. [Data flow and authentication](docs/reference.md#data-flow-and-authentication).
 - Subscription access and usage limits still apply. Model switches can reduce cache reuse; cheaper token prices do not guarantee cheaper completed tasks. Run ordinary `claude` to bypass routing.
 - The launcher is quiet by default. Use `AUTOROUTER_DEBUG=1` for metadata diagnostics or `AUTOROUTER_STATUSLINE=0` to retain your existing status line. [Troubleshooting](docs/reference.md#troubleshooting).
+- For blocked `/goal` loops, optionally launch with `env CLAUDE_CODE_STOP_HOOK_BLOCK_CAP=2 claude-autorouter claude`. Claude then ends the turn on the third consecutive blocking verdict without tool use, leaving the goal unmet. This also affects other Stop/SubagentStop hooks; defaults are unchanged. [Scope and saved configuration](docs/reference.md#shorter-stop-hook-loops-opt-in).
 
 [Reference](docs/reference.md) · [Development and validation](docs/development.md) · [CI and npm release setup](docs/releasing.md) · [Apache-2.0 license](LICENSE)

package/bin/autorouter.mjs

@@ -23,6 +23,7 @@ Usage:
   claude-autorouter setup [--auth-mode subscription|api-key] [--force]
     [--evaluator jev|ollama]
     [--ollama-model MODEL] [--ollama-timeout-ms N] [--pull]
+    [--stop-hook-block-cap N]
   claude-autorouter doctor
   claude-autorouter claude [Claude Code arguments]
   claude-autorouter serve
@@ -47,6 +48,9 @@ AUTOROUTER_AUTH_MODE=subscription uses your saved Claude Code login.
 Without setup, AUTOROUTER_AUTH_MODE defaults to api-key and also requires ANTHROPIC_API_KEY.
 AUTOROUTER_CLIENT_PROFILE=compatible (default) enables all three routing tiers.
 Use AUTOROUTER_CLIENT_PROFILE=native to retain Claude Code's own model/thinking settings.
+Optional CLAUDE_CODE_STOP_HOOK_BLOCK_CAP=N limits consecutive tool-free Stop-hook continuations.
+Use 2 to stop on the third block; applies to /goal and all Stop/SubagentStop hooks.
+Unset preserves Claude's default; 0 disables the cap. Setup --stop-hook-block-cap N saves it.
 Standalone serve also requires AUTOROUTER_TOKEN (at least 16 characters).
 The claude launcher creates a temporary credential and an ephemeral port.
 It enables an AutoRouter status line for this session (AUTOROUTER_STATUSLINE=0 to opt out).

package/docs/reference.md

@@ -6,6 +6,7 @@
 | --- | --- |
 | `claude-autorouter setup` | Save subscription-mode configuration and a Jev key |
 | `claude-autorouter setup --auth-mode api-key` | Configure Jev and Anthropic API-key billing |
+| `claude-autorouter setup --stop-hook-block-cap 2` | Opt into a shorter native Stop-hook continuation cap during setup |
 | `claude-autorouter setup --evaluator ollama --pull` | Configure the native local evaluator and download its selected model if missing |
 | `claude-autorouter setup --evaluator ollama --ollama-timeout-ms 0 --force` | Save a disabled runtime evaluator deadline |
 | `claude-autorouter setup --force` | Replace an existing user config |
@@ -45,6 +46,7 @@ For an environment-only subscription launch, set `AUTOROUTER_AUTH_MODE=subscript
 | `AUTOROUTER_CLIENT_PROFILE` | `compatible` | `native` retains Claude's own model and thinking settings |
 | `AUTOROUTER_STATUSLINE` | enabled | `0` retains your existing status line |
 | `AUTOROUTER_DEBUG` | off | `1` enables launcher metadata logs on stderr |
+| `CLAUDE_CODE_STOP_HOOK_BLOCK_CAP` | unset; Claude currently uses `8` | Optional cap on consecutive Stop/SubagentStop continuations without tool use; `0` disables the cap |
 | `ENABLE_TOOL_SEARCH` | `true` in launcher when unset | Load MCP tool definitions on demand; explicit values are preserved |
 | `AUTOROUTER_HAIKU_MODEL` | `claude-haiku-4-5-20251001` | Routine tier |
 | `AUTOROUTER_SONNET_MODEL` | `claude-sonnet-5` | Standard tier |
@@ -238,6 +240,26 @@ The launcher is quiet by default. Standalone `serve` logs to stderr by default.
 
 If the worker reports a blocker but the checker keeps returning “not yet met,” Claude can repeat its answer until its no-progress guard pauses the goal. Repeated tool calls can keep the loop running longer. Use `/goal clear` to end the loop, resolve the external blocker, and set the goal again. For tasks that may require human action, explicitly allow reporting a blocker as an alternative end condition, for example: `/goal Verify the discrepancy against upstream main and run the relevant tests, or report an external authorization blocker and stop.` This changes what counts as completion; AutoRouter does not declare blocked work successful or rewrite goal instructions. See [Claude Code goal evaluation](https://code.claude.com/docs/en/goal#how-evaluation-works).
 
+### Shorter Stop-hook loops (opt-in)
+
+To return control sooner when a goal keeps reporting the same unmet condition, set Claude's native continuation cap for one launch:
+
+```sh
+env CLAUDE_CODE_STOP_HOOK_BLOCK_CAP=2 claude-autorouter claude
+```
+
+This permits two consecutive continuations without tool use; the third blocking verdict ends the turn. The goal remains set and unmet, and a new message can resume it. Tool activity resets the counter, so this is not a total turn or request limit and cannot bound repeated failed tool calls. It applies to **all Stop and SubagentStop hooks**, including `/goal`. A smaller cap can pause useful work sooner. Unset preserves Claude's default (currently `8`); **`0` disables the guard**. AutoRouter does not install a Stop hook or change completion verdicts. See [Claude's environment-variable reference](https://code.claude.com/docs/en/env-vars) and [Stop-hook loop behavior](https://code.claude.com/docs/en/hooks#stop).
+
+The environment-only command also works on AutoRouter 0.3.4. Saved configuration and the setup flag require AutoRouter 0.3.5 or newer. To save the preference, add the following property to your existing AutoRouter config JSON, preserving its other values:
+
+```json
+"CLAUDE_CODE_STOP_HOOK_BLOCK_CAP": "2"
+```
+
+For a new configuration, use `claude-autorouter setup --stop-hook-block-cap 2`; the flag works with either evaluator and overrides the environment during setup. Runtime environment values override saved configuration. `setup --force` replaces the entire config, so keep your existing evaluator/authentication options if using it. `doctor` reports the cap when configured. AutoRouter accepts nonnegative safe integers and leaves the setting absent unless you opt in.
+
+### Other session issues
+
 **After restarting mid-conversation:** turn state is in memory and expires after 30 minutes. Unknown continuations preserve the incoming model. Start a fresh conversation when restarting around signed thinking; AutoRouter cannot reconstruct the prior actual model from lost turn state.
 
 Switching models can lose prompt-cache reuse. A cheaper price per token does not guarantee a cheaper or faster task. Only requests using Claude's configured base URL are visible to this proxy. Alternate provider modes such as Bedrock, Vertex, Foundry, Mantle, and `ANTHROPIC_AWS` are unsupported; unset their enable flags before launching. Use ordinary `claude` to bypass routing.

package/docs/releasing.md

@@ -10,6 +10,8 @@ Version `0.3.3` fixes HTTP 400 errors when a compatible request with disabled th
 
 Version `0.3.4` preserves the selected model across Stop-hook feedback for the same prompt, including `/goal` commands that omit the gateway prompt-ID header. Recognized goal feedback remains conversation context rather than replacing the human task in evaluator excerpts. Goal-checker verdicts remain unchanged; external authorization blockers can still cause Claude's own goal loop to repeat. See [goal troubleshooting](reference.md#troubleshooting).
 
+Version `0.3.5` adds opt-in saved configuration for Claude's native `CLAUDE_CODE_STOP_HOOK_BLOCK_CAP`, with `setup --stop-hook-block-cap N`, validation, and `doctor` reporting. A value of `2` permits two consecutive Stop-hook continuations without tool use and ends the turn on the third blocking verdict, leaving an unmet goal set. This affects all Stop/SubagentStop hooks, and tool activity resets the counter. Defaults and completion verdicts are unchanged; `0` disables the guard. See [shorter Stop-hook loops](reference.md#shorter-stop-hook-loops-opt-in).
+
 The GitHub repository is private. Publishing to npm makes the tarball's runtime source, README, configuration example, license, and shipped documentation public. Model weights, user configuration, credentials, transcripts, local artifacts, and test fixtures are excluded. Review the archive before the first publication and whenever the package allowlist changes.
 
 ## What runs automatically

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-autorouter",
-  "version": "0.3.4",
+  "version": "0.3.5",
   "license": "Apache-2.0",
   "type": "module",
   "description": "A Claude Code model router with Jev and local Ollama System One evaluators",

package/src/auth.mjs

@@ -16,6 +16,11 @@ export function isSubscriptionRequest(headers) {
 
 export function buildClaudeEnv(config, baseUrl, parent = process.env) {
   const env = { ...parent, ANTHROPIC_BASE_URL: baseUrl, CLAUDE_CODE_GATEWAY_HINT_HEADERS: '1' };
+  // Opt into Claude's own loop guard without installing hooks or altering
+  // their verdicts. An unset cap leaves Claude's default in control.
+  if (env.CLAUDE_CODE_STOP_HOOK_BLOCK_CAP === undefined && config.stopHookBlockCap !== undefined) {
+    env.CLAUDE_CODE_STOP_HOOK_BLOCK_CAP = String(config.stopHookBlockCap);
+  }
   // Claude Code otherwise disables MCP tool search for a non-first-party
   // base URL and loads every schema into context. This proxy preserves both
   // tool_reference blocks and their beta headers. Respect explicit choices.

package/src/config.mjs

@@ -2,6 +2,15 @@ import { DEFAULT_OLLAMA_MODEL, defaultOllamaTimeoutMs, validateOllamaEndpoint, v
 
 export const TIERS = ['haiku', 'sonnet', 'opus'];
 
+export function parseStopHookBlockCap(value, name = 'CLAUDE_CODE_STOP_HOOK_BLOCK_CAP') {
+  if (!['string', 'number'].includes(typeof value)
+    || (typeof value === 'string' && !/^[0-9]+$/.test(value.trim()))
+    || !Number.isSafeInteger(Number(value)) || Number(value) < 0) {
+    throw new Error(`${name} requires a nonnegative safe integer (0 disables the Stop-hook continuation cap)`);
+  }
+  return Number(value);
+}
+
 function number(env, key, fallback, min, max, integer = true) {
   const value = Number(env[key] ?? fallback);
   if (!Number.isFinite(value) || value < min || value > max || (integer && !Number.isInteger(value))) {
@@ -50,6 +59,8 @@ export function readConfig(env = process.env) {
     evaluator,
     authMode,
     clientProfile,
+    stopHookBlockCap: env.CLAUDE_CODE_STOP_HOOK_BLOCK_CAP === undefined
+      ? undefined : parseStopHookBlockCap(env.CLAUDE_CODE_STOP_HOOK_BLOCK_CAP),
     anthropicKey: authMode === 'api-key' ? env.ANTHROPIC_API_KEY : undefined,
     jevKey: env.TYPESAFE_API_KEY,
     localToken: env.AUTOROUTER_TOKEN,

package/src/onboarding.mjs

@@ -3,7 +3,7 @@ import { existsSync } from 'node:fs';
 import { createInterface } from 'node:readline';
 import { Writable } from 'node:stream';
 import { promisify } from 'node:util';
-import { readConfig, requireKeys } from './config.mjs';
+import { readConfig, requireKeys, parseStopHookBlockCap } from './config.mjs';
 import { buildClaudeEnv, conflictingProviders, LOCAL_AUTH_HEADER } from './auth.mjs';
 import { getConfigPath, loadUserConfig, saveUserConfig } from './user-config.mjs';
 import { DEFAULT_OLLAMA_MODEL, validateOllamaModel } from './ollama-models.mjs';
@@ -14,6 +14,10 @@ const execute = promisify(execFile);
 export const ollamaDeadlineText = timeoutMs => timeoutMs === 0
   ? 'routing deadline disabled' : `routing deadline ${timeoutMs} ms per request`;
 
+const stopHookCapText = cap => cap === 0
+  ? 'Claude Stop/SubagentStop continuation cap disabled (0).'
+  : `Claude Stop/SubagentStop cap: ${cap} continuations without tool use.`;
+
 // Readline manages editing and restores terminal state; its output is discarded
 // so neither typing nor pasted credentials are echoed to the terminal.
 export async function askSecret(label, { input = process.stdin, output = process.stderr } = {}) {
@@ -40,6 +44,7 @@ export async function setup(args, {
   let evaluator = env.AUTOROUTER_EVALUATOR ?? 'jev';
   let model;
   let ollamaTimeoutMs;
+  let stopHookBlockCap = env.CLAUDE_CODE_STOP_HOOK_BLOCK_CAP;
   let pull = false;
   let overwrite = false;
   for (let i = 0; i < args.length; i++) {
@@ -53,19 +58,24 @@ export async function setup(args, {
       }
       ollamaTimeoutMs = String(Number(value));
     }
+    else if (args[i] === '--stop-hook-block-cap') {
+      stopHookBlockCap = parseStopHookBlockCap(args[++i], '--stop-hook-block-cap');
+    }
     else if (args[i] === '--pull') pull = true;
     else if (args[i] === '--force') overwrite = true;
-    else throw new Error('Usage: claude-autorouter setup [--auth-mode subscription|api-key] [--evaluator jev|ollama] [--ollama-model TAG] [--ollama-timeout-ms N] [--pull] [--force]');
+    else throw new Error('Usage: claude-autorouter setup [--auth-mode subscription|api-key] [--evaluator jev|ollama] [--ollama-model TAG] [--ollama-timeout-ms N] [--stop-hook-block-cap N] [--pull] [--force]');
   }
   if (!['subscription', 'api-key'].includes(authMode)) throw new Error('--auth-mode must be subscription or api-key');
   if (!['jev', 'ollama'].includes(evaluator)) throw new Error('--evaluator must be jev or ollama');
   if (evaluator !== 'ollama' && (model !== undefined || ollamaTimeoutMs !== undefined || pull)) throw new Error('Ollama model, deadline and download options require --evaluator ollama');
+  if (stopHookBlockCap !== undefined) stopHookBlockCap = parseStopHookBlockCap(stopHookBlockCap);
   const path = getConfigPath(env);
   if (!overwrite && existsSync(path)) throw new Error('AutoRouter configuration already exists. Use setup --force to replace it.');
   write(evaluator === 'ollama'
     ? 'AutoRouter evaluates bounded prompt excerpts locally with Ollama. Complete requests still go to Anthropic.'
     : 'AutoRouter sends bounded prompt excerpts to TypeSafe Jev and complete requests to Anthropic.');
   const values = { AUTOROUTER_AUTH_MODE: authMode, AUTOROUTER_CLIENT_PROFILE: 'compatible', AUTOROUTER_EVALUATOR: evaluator };
+  if (stopHookBlockCap !== undefined) values.CLAUDE_CODE_STOP_HOOK_BLOCK_CAP = String(stopHookBlockCap);
   if (evaluator === 'ollama') {
     values.AUTOROUTER_OLLAMA_MODEL = validateOllamaModel(model ?? env.AUTOROUTER_OLLAMA_MODEL ?? DEFAULT_OLLAMA_MODEL);
     for (const key of ['AUTOROUTER_OLLAMA_URL', 'AUTOROUTER_OLLAMA_TIMEOUT_MS', 'AUTOROUTER_OLLAMA_KEEP_ALIVE']) {
@@ -81,6 +91,7 @@ export async function setup(args, {
   }
   const config = readConfig(values);
   requireKeys(config);
+  if (config.stopHookBlockCap !== undefined) write(stopHookCapText(config.stopHookBlockCap));
   if (evaluator === 'ollama') {
     write(`Local evaluator: ${config.ollamaModel}; ${ollamaDeadlineText(config.ollamaTimeoutMs)}.`);
     const controller = new AbortController();
@@ -115,6 +126,7 @@ export async function doctor({ env = process.env, write = console.log, run = exe
   for (const key of conflictingProviders(effectiveEnv)) {
     report(false, `Unset ${key}; AutoRouter uses the Anthropic Messages API`);
   }
+  if (config?.stopHookBlockCap !== undefined) write(stopHookCapText(config.stopHookBlockCap));
   if (config?.evaluator === 'ollama') {
     write(`Local evaluator: ${config.ollamaModel}; ${ollamaDeadlineText(config.ollamaTimeoutMs)}.`);
     write('Model availability is checked below; classification speed and accuracy are not tested.');

package/src/user-config.mjs

@@ -13,7 +13,7 @@ const CONFIG_KEYS = new Set([
   'AUTOROUTER_HAIKU_MODEL', 'AUTOROUTER_SONNET_MODEL', 'AUTOROUTER_OPUS_MODEL',
   'AUTOROUTER_PORT', 'AUTOROUTER_JEV_TIMEOUT_MS', 'AUTOROUTER_TOKEN_COUNT_TIMEOUT_MS',
   'AUTOROUTER_MIN_CONFIDENCE', 'AUTOROUTER_STATUSLINE', 'AUTOROUTER_DEBUG',
-  'ENABLE_TOOL_SEARCH',
+  'ENABLE_TOOL_SEARCH', 'CLAUDE_CODE_STOP_HOOK_BLOCK_CAP',
   'AUTOROUTER_EVALUATOR', 'AUTOROUTER_OLLAMA_URL', 'AUTOROUTER_OLLAMA_MODEL',
   'AUTOROUTER_OLLAMA_TIMEOUT_MS', 'AUTOROUTER_OLLAMA_KEEP_ALIVE',
 ]);