scootcli 0.2.0__tar.gz → 0.4.0__tar.gz

{scootcli-0.2.0/src/scootcli.egg-info → scootcli-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: scootcli
-Version: 0.2.0
+Version: 0.4.0
 Summary: A tiny coding agent that goes where you point it
 Author: Sergey Nes
 License-Expression: MIT
@@ -36,7 +36,7 @@ Dynamic: license-file
 ```
        ╭───╮      scoot: a tiny coding agent that goes where you point it.
        │o o│
-    T──┤───┤      pipx install scootcli
+    T──┤───┤      pipx install scootcli   (or: curl -fsSL https://raw.githubusercontent.com/sergenes/scootcli/main/install.sh | bash)
     │  ╰┬─┬╯      scoot
   (o)═══╧═╧═(o)
 ```
@@ -61,12 +61,19 @@ The naive version did real work in my repos for long enough that the next step w
 ## Quick start
 
 ```bash
-pipx install scootcli            # or: pip install scootcli
+pipx install scootcli && pipx ensurepath   # then open a new terminal so `scoot` is on PATH
 scoot auth set openai            # paste your OpenAI API key once (hidden input, validated, stored 0600)
 cd ~/code/your-project
 scoot                            # open the REPL
 ```
 
+No pipx yet? On Debian, Ubuntu, and Pop!_OS it is `sudo apt install pipx`; on macOS `brew install pipx`.
+Or skip pipx entirely with the one-line installer, which needs only `curl` and Python 3.9+:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/sergenes/scootcli/main/install.sh | bash
+```
+
 Or run entirely local with [Ollama](https://ollama.com), no key at all:
 
 ```bash
@@ -74,6 +81,9 @@ ollama pull llama3.2
 scoot --model ollama/llama3.2
 ```
 
+**First run.** With no key saved and no Ollama running, scoot still opens: the banner says "no provider set up yet", a short block lists the three ways to set one up, and the bar shows `not set up` until a provider can answer.
+Run `scoot auth set openai` (or `anthropic`) inside the REPL and the bar switches to the real provider and model at once.
+
 The first prompt:
 
 ```
@@ -106,6 +116,36 @@ scoot --model auto "..."             # pick a model per prompt from the live lis
 ```
 
 Inside the REPL, `/model <provider/model>` switches and is remembered for the next launch; `/model default` goes back to the provider's preferred model.
+
+### Routing
+
+`auto` is opt-in (`--model auto`, `SCOOT_MODEL=auto`, or `/model auto`) because choosing costs a decision per turn.
+Without any configuration it uses a built-in heuristic over the models your providers actually list: a strong coding model for multi-step or editing prompts, a cheaper one for short questions, never a dated snapshot.
+A turn is routed once, at its first model call, and stays on that model.
+
+Write your own rules in `~/.config/scoot/router.json` (or the file named by `SCOOT_ROUTER`); first match wins, and a rule whose provider has no key is skipped:
+
+```json
+{
+  "rules": [
+    {"when": {"has_images": true},        "use": "anthropic/claude-opus-5"},
+    {"when": {"complex": true},           "use": "openai/gpt-5.3-codex"},
+    {"when": {"est_tokens_over": 60000},  "use": "anthropic/claude-sonnet-5"},
+    {"when": {"prompt_matches": "(?i)translate|summari[sz]e"}, "use": "ollama/qwen3"}
+  ],
+  "default": "ollama/llama3.2",
+  "classifier": {
+    "model": "ollama/llama3.2",
+    "tiers": {"simple": "ollama/llama3.2", "coding": "openai/gpt-5.3-codex", "hard": "anthropic/claude-opus-5"}
+  }
+}
+```
+
+Conditions: `complex`, `has_images`, `needs_tools`, `est_tokens_over`, `prompt_matches`.
+The optional `classifier` asks a small model one question per turn ("simple, coding, or hard?") and maps the answer to a tier; it adds a short call, and any failure falls through to the rules.
+Expect it to be rough with a 3B local model: on a hand-labelled set of seven prompts, `llama3.2` and `qwen2.5` each got four right, mostly confusing "coding" with "hard".
+The rules are deterministic, so put the decisions you care about there, and if you want a better judge, name a cheap hosted model as the classifier (`openai/gpt-5-mini`), which costs a few hundred tokens per turn.
+`/route` shows the rules in force and why the current model was picked; `/status` shows tokens per model.
 `SCOOT_EFFORT` (`low` | `medium` | `high` | `xhigh`, default `medium`) sets the reasoning effort for models that take it, on both OpenAI and Anthropic.
 On Claude Opus 5 the server-side refusal fallback is requested by default, so a declined request is retried on another Claude model inside the same call; `SCOOT_ANTHROPIC_FALLBACKS=0` turns that off.
 
@@ -197,6 +237,29 @@ Responses stream live and stay interruptible.
 Drag an image into the prompt and a vision-capable model describes it into the turn as text, so even a text-only coding model can act on it; `SCOOT_VISION_MODEL` pins the describer, `--no-images` turns the feature off.
 Every turn auto-saves under `~/.local/state/scoot/sessions/` (owner-only, secrets redacted, last 20 kept); `scoot --continue` or `/resume` picks up where you left off.
 
+### Automation: hooks and headless mode
+
+**Hooks** run your own scripts at lifecycle events: `SessionStart`, `UserPromptSubmit`, `PreToolUse`, `PostToolUse`, `Stop`, `Notification`, `SessionEnd`.
+A hook gets a JSON payload on stdin and answers with an exit code or JSON on stdout; the shapes follow the convention Claude Code established, so a script written for one works with the other.
+Put them in `~/.config/scoot/hooks.json` or `.scoot/hooks.json` in the project:
+
+```json
+{
+  "PreToolUse": [
+    {"matcher": "run_shell|write_file|edit_file", "hooks": [{"type": "command", "command": "~/bin/guard.py", "timeout": 30}]}
+  ],
+  "Stop": [{"hooks": [{"type": "command", "command": "~/bin/notify.sh"}]}]
+}
+```
+
+A `PreToolUse` hook can answer `{"permissionDecision": "deny", "reason": "..."}` to skip a tool (the model is told why), `allow` to skip the approval prompt, or `ask` to force one even in `yolo`; exit code 2 denies with stderr as the reason.
+A `Stop` hook that answers `{"decision": "block", "reason": "run the tests first"}` sends the agent back to work with that instruction, at most three times per turn.
+`/hooks` shows what is configured and what ran; `SCOOT_HOOKS=0` turns hooks off.
+
+**Headless mode** is for editors, automation, and remote-control tools: `scoot --headless` reads JSON lines on stdin (`prompt`, `approve`, `note`, `interrupt`, `command`, `shutdown`) and writes JSON lines on stdout (streamed text, tool calls, approval requests, results, plan updates, usage, errors, a heartbeat), with nothing else ever printed there.
+Same sessions, tools, approvals, routing, and hooks as the REPL.
+The message tables and a full transcript are in [`docs/headless-protocol.md`](./docs/headless-protocol.md); an unanswered approval is denied after `SCOOT_APPROVAL_TIMEOUT` seconds (default 120).
+
 ### The status bar
 
 The bottom row shows the mascot's face (its eyes follow the turn: `o o` idle, `> >` thinking, `- -` stopped), the provider, the workspace and session id, the model, the approval mode, context size against the auto-compact threshold, cumulative tokens, message count, and the last error if any.
@@ -204,12 +267,16 @@ The bottom row shows the mascot's face (its eyes follow the turn: `o o` idle, `>
 ## Install options
 
 ```bash
-pipx install scootcli                          # recommended: isolated, `scoot` on PATH
+pipx install scootcli && pipx ensurepath       # recommended: isolated; ensurepath puts ~/.local/bin on PATH for new shells
+curl -fsSL https://raw.githubusercontent.com/sergenes/scootcli/main/install.sh | bash   # no pipx: puts the zipapp at ~/.local/bin/scoot
 pip install scootcli                           # anywhere
 curl -LO https://github.com/sergenes/scootcli/releases/latest/download/scoot.pyz && python3 scoot.pyz  # single file, no install
 git clone https://github.com/sergenes/scootcli && cd scootcli && pip install -e .                       # from source
 ```
 
+The install script needs only `curl` and Python 3.9+. `SCOOT_VERSION=v0.2.0` pins a release and `SCOOT_INSTALL_DIR` changes the target; read it before you run it, it is sixty lines.
+Both pipx and the script install into `~/.local/bin`. On a fresh Linux account that directory is added to PATH at login only if it already exists, so after the very first install either open a new login shell or run `pipx ensurepath`; the installer prints the exact line for your shell.
+
 Requirements: Python 3.9 or newer on macOS or Linux.
 Nothing else: no compiler, no packages, no `curl`.
 

{scootcli-0.2.0 → scootcli-0.4.0}/README.md

@@ -11,7 +11,7 @@
 ```
        ╭───╮      scoot: a tiny coding agent that goes where you point it.
        │o o│
-    T──┤───┤      pipx install scootcli
+    T──┤───┤      pipx install scootcli   (or: curl -fsSL https://raw.githubusercontent.com/sergenes/scootcli/main/install.sh | bash)
     │  ╰┬─┬╯      scoot
   (o)═══╧═╧═(o)
 ```
@@ -36,12 +36,19 @@ The naive version did real work in my repos for long enough that the next step w
 ## Quick start
 
 ```bash
-pipx install scootcli            # or: pip install scootcli
+pipx install scootcli && pipx ensurepath   # then open a new terminal so `scoot` is on PATH
 scoot auth set openai            # paste your OpenAI API key once (hidden input, validated, stored 0600)
 cd ~/code/your-project
 scoot                            # open the REPL
 ```
 
+No pipx yet? On Debian, Ubuntu, and Pop!_OS it is `sudo apt install pipx`; on macOS `brew install pipx`.
+Or skip pipx entirely with the one-line installer, which needs only `curl` and Python 3.9+:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/sergenes/scootcli/main/install.sh | bash
+```
+
 Or run entirely local with [Ollama](https://ollama.com), no key at all:
 
 ```bash
@@ -49,6 +56,9 @@ ollama pull llama3.2
 scoot --model ollama/llama3.2
 ```
 
+**First run.** With no key saved and no Ollama running, scoot still opens: the banner says "no provider set up yet", a short block lists the three ways to set one up, and the bar shows `not set up` until a provider can answer.
+Run `scoot auth set openai` (or `anthropic`) inside the REPL and the bar switches to the real provider and model at once.
+
 The first prompt:
 
 ```
@@ -81,6 +91,36 @@ scoot --model auto "..."             # pick a model per prompt from the live lis
 ```
 
 Inside the REPL, `/model <provider/model>` switches and is remembered for the next launch; `/model default` goes back to the provider's preferred model.
+
+### Routing
+
+`auto` is opt-in (`--model auto`, `SCOOT_MODEL=auto`, or `/model auto`) because choosing costs a decision per turn.
+Without any configuration it uses a built-in heuristic over the models your providers actually list: a strong coding model for multi-step or editing prompts, a cheaper one for short questions, never a dated snapshot.
+A turn is routed once, at its first model call, and stays on that model.
+
+Write your own rules in `~/.config/scoot/router.json` (or the file named by `SCOOT_ROUTER`); first match wins, and a rule whose provider has no key is skipped:
+
+```json
+{
+  "rules": [
+    {"when": {"has_images": true},        "use": "anthropic/claude-opus-5"},
+    {"when": {"complex": true},           "use": "openai/gpt-5.3-codex"},
+    {"when": {"est_tokens_over": 60000},  "use": "anthropic/claude-sonnet-5"},
+    {"when": {"prompt_matches": "(?i)translate|summari[sz]e"}, "use": "ollama/qwen3"}
+  ],
+  "default": "ollama/llama3.2",
+  "classifier": {
+    "model": "ollama/llama3.2",
+    "tiers": {"simple": "ollama/llama3.2", "coding": "openai/gpt-5.3-codex", "hard": "anthropic/claude-opus-5"}
+  }
+}
+```
+
+Conditions: `complex`, `has_images`, `needs_tools`, `est_tokens_over`, `prompt_matches`.
+The optional `classifier` asks a small model one question per turn ("simple, coding, or hard?") and maps the answer to a tier; it adds a short call, and any failure falls through to the rules.
+Expect it to be rough with a 3B local model: on a hand-labelled set of seven prompts, `llama3.2` and `qwen2.5` each got four right, mostly confusing "coding" with "hard".
+The rules are deterministic, so put the decisions you care about there, and if you want a better judge, name a cheap hosted model as the classifier (`openai/gpt-5-mini`), which costs a few hundred tokens per turn.
+`/route` shows the rules in force and why the current model was picked; `/status` shows tokens per model.
 `SCOOT_EFFORT` (`low` | `medium` | `high` | `xhigh`, default `medium`) sets the reasoning effort for models that take it, on both OpenAI and Anthropic.
 On Claude Opus 5 the server-side refusal fallback is requested by default, so a declined request is retried on another Claude model inside the same call; `SCOOT_ANTHROPIC_FALLBACKS=0` turns that off.
 
@@ -172,6 +212,29 @@ Responses stream live and stay interruptible.
 Drag an image into the prompt and a vision-capable model describes it into the turn as text, so even a text-only coding model can act on it; `SCOOT_VISION_MODEL` pins the describer, `--no-images` turns the feature off.
 Every turn auto-saves under `~/.local/state/scoot/sessions/` (owner-only, secrets redacted, last 20 kept); `scoot --continue` or `/resume` picks up where you left off.
 
+### Automation: hooks and headless mode
+
+**Hooks** run your own scripts at lifecycle events: `SessionStart`, `UserPromptSubmit`, `PreToolUse`, `PostToolUse`, `Stop`, `Notification`, `SessionEnd`.
+A hook gets a JSON payload on stdin and answers with an exit code or JSON on stdout; the shapes follow the convention Claude Code established, so a script written for one works with the other.
+Put them in `~/.config/scoot/hooks.json` or `.scoot/hooks.json` in the project:
+
+```json
+{
+  "PreToolUse": [
+    {"matcher": "run_shell|write_file|edit_file", "hooks": [{"type": "command", "command": "~/bin/guard.py", "timeout": 30}]}
+  ],
+  "Stop": [{"hooks": [{"type": "command", "command": "~/bin/notify.sh"}]}]
+}
+```
+
+A `PreToolUse` hook can answer `{"permissionDecision": "deny", "reason": "..."}` to skip a tool (the model is told why), `allow` to skip the approval prompt, or `ask` to force one even in `yolo`; exit code 2 denies with stderr as the reason.
+A `Stop` hook that answers `{"decision": "block", "reason": "run the tests first"}` sends the agent back to work with that instruction, at most three times per turn.
+`/hooks` shows what is configured and what ran; `SCOOT_HOOKS=0` turns hooks off.
+
+**Headless mode** is for editors, automation, and remote-control tools: `scoot --headless` reads JSON lines on stdin (`prompt`, `approve`, `note`, `interrupt`, `command`, `shutdown`) and writes JSON lines on stdout (streamed text, tool calls, approval requests, results, plan updates, usage, errors, a heartbeat), with nothing else ever printed there.
+Same sessions, tools, approvals, routing, and hooks as the REPL.
+The message tables and a full transcript are in [`docs/headless-protocol.md`](./docs/headless-protocol.md); an unanswered approval is denied after `SCOOT_APPROVAL_TIMEOUT` seconds (default 120).
+
 ### The status bar
 
 The bottom row shows the mascot's face (its eyes follow the turn: `o o` idle, `> >` thinking, `- -` stopped), the provider, the workspace and session id, the model, the approval mode, context size against the auto-compact threshold, cumulative tokens, message count, and the last error if any.
@@ -179,12 +242,16 @@ The bottom row shows the mascot's face (its eyes follow the turn: `o o` idle, `>
 ## Install options
 
 ```bash
-pipx install scootcli                          # recommended: isolated, `scoot` on PATH
+pipx install scootcli && pipx ensurepath       # recommended: isolated; ensurepath puts ~/.local/bin on PATH for new shells
+curl -fsSL https://raw.githubusercontent.com/sergenes/scootcli/main/install.sh | bash   # no pipx: puts the zipapp at ~/.local/bin/scoot
 pip install scootcli                           # anywhere
 curl -LO https://github.com/sergenes/scootcli/releases/latest/download/scoot.pyz && python3 scoot.pyz  # single file, no install
 git clone https://github.com/sergenes/scootcli && cd scootcli && pip install -e .                       # from source
 ```
 
+The install script needs only `curl` and Python 3.9+. `SCOOT_VERSION=v0.2.0` pins a release and `SCOOT_INSTALL_DIR` changes the target; read it before you run it, it is sixty lines.
+Both pipx and the script install into `~/.local/bin`. On a fresh Linux account that directory is added to PATH at login only if it already exists, so after the very first install either open a new login shell or run `pipx ensurepath`; the installer prints the exact line for your shell.
+
 Requirements: Python 3.9 or newer on macOS or Linux.
 Nothing else: no compiler, no packages, no `curl`.
 

{scootcli-0.2.0 → scootcli-0.4.0}/src/scootcli/__init__.py

@@ -1,4 +1,4 @@
 """scoot: a tiny coding agent that goes where you point it."""
 
-__version__ = "0.2.0"
+__version__ = "0.4.0"
 

{scootcli-0.2.0 → scootcli-0.4.0}/src/scootcli/agent.py

@@ -97,6 +97,7 @@ class Agent:
         self._refresh_workspace(session, cfg)
         steps = 0
         compacted = False
+        stop_blocks = 0
         while True:
             if cancel_event.is_set():
                 return AgentOutcome("interrupted", steps=steps)
@@ -129,7 +130,10 @@ class Agent:
             except ScootError as exc:
                 return AgentOutcome("error", error=_fmt_error(exc), steps=steps)
 
-            session.account(result.usage)
+            try:
+                session.account(result.usage, model=result.model or session.active_model)
+            except TypeError:  # older/fake sessions with a one-argument account()
+                session.account(result.usage)
             session.messages.append(self._assistant_message(result))
 
             if result.tool_calls:
@@ -141,10 +145,16 @@ class Agent:
                     return AgentOutcome(status, steps=steps)
                 continue
 
-            # No tool calls -> the model is done.
-            return AgentOutcome(
-                "done", content=_strip_done(result.content), steps=steps, streamed=streamed
-            )
+            # No tool calls -> the model is done, unless a Stop hook asks for more (bounded).
+            content = _strip_done(result.content)
+            if stop_blocks < 3:
+                reason = self._stop_hook(session, content, steps)
+                if reason:
+                    stop_blocks += 1
+                    session.messages.append({"role": "user", "content": reason})
+                    ui.assistant(f"continuing: {reason}")
+                    continue
+            return AgentOutcome("done", content=content, steps=steps, streamed=streamed)
 
     # ── model call (streaming or buffered) ───────────────────────────────────────
     def _model_call(self, session, cfg, ui, cancel_event, steps):
@@ -178,6 +188,45 @@ class Agent:
             )
         return result, False
 
+    # ── hooks ────────────────────────────────────────────────────────────────────
+    @staticmethod
+    def _hooks(session):
+        from .hooks import for_session
+
+        return for_session(session)
+
+    def _stop_hook(self, session, content: str, steps: int) -> str:
+        hooks = self._hooks(session)
+        if hooks is None or not hooks.has("Stop"):
+            return ""
+        payload = hooks.payload(session, "Stop", last_assistant_message=content, steps=steps,
+                                usage=getattr(session, "last_usage", {}) or {})
+        decision = hooks.run("Stop", payload)
+        return (decision.reason or "the Stop hook asked to continue") if decision.blocks else ""
+
+    def _pre_tool_hook(self, session, tool, args, cancel_event) -> "tuple[str, str]":
+        hooks = self._hooks(session)
+        if hooks is None or not hooks.has("PreToolUse"):
+            return "", ""
+        from .hooks import tool_kind
+
+        payload = hooks.payload(session, "PreToolUse", tool_name=tool.name, tool_input=args,
+                                tool_kind=tool_kind(tool))
+        decision = hooks.run("PreToolUse", payload, cancel_event)
+        return decision.action, decision.reason
+
+    def _post_tool_hook(self, session, tool, args, result: ToolResult) -> None:
+        hooks = self._hooks(session)
+        if hooks is None or not hooks.has("PostToolUse"):
+            return
+        from .hooks import tool_kind
+
+        response = {"ok": result.ok, "summary": result.summary or "", "error": result.error or "",
+                    "content": (result.content or "")[:4000]}
+        hooks.run("PostToolUse", hooks.payload(session, "PostToolUse", tool_name=tool.name,
+                                               tool_input=args, tool_kind=tool_kind(tool),
+                                               tool_response=response))
+
     @staticmethod
     def _last_user_text(session) -> str:
         for m in reversed(getattr(session, "messages", []) or []):
@@ -187,19 +236,33 @@ class Agent:
 
     # ── message construction ─────────────────────────────────────────────────────
     def _pick_model(self, session) -> str:
-        """Resolve the model for this turn. For ``auto``, use the heuristic over live models."""
+        """Resolve the model for this turn. ``auto`` routes once per turn (see ``providers.router``)."""
         if session.model.lower() != "auto":
             return session.resolved_model()
-        from .models import resolve_auto
+        from .providers.router import Router, compute_hints
 
-        last_user = self._last_user_text(session)
+        router = getattr(session, "router", None)
+        if router is None:
+            router = Router()
+            try:
+                session.router = router
+            except Exception:
+                pass
         try:
             available = session.available_models()
         except Exception:
             available = []
         bad = getattr(session, "bad_models", None) or set()
         available = [m for m in available if m not in bad] or available
-        return resolve_auto(last_user, available, fallback=session.resolved_model())
+        hints = compute_hints(session)
+        return router.choose(session, hints, available, session.resolved_model(),
+                             classify=self._classify_with_provider).model
+
+    def _classify_with_provider(self, model: str, prompt: str) -> str:
+        """One small, non-streaming call used by a configured router classifier."""
+        result = self.provider.chat([{"role": "user", "content": prompt}], model=model, max_tokens=5,
+                                    temperature=0, hints={"purpose": "route"})
+        return result.content or ""
 
     def _fallback_model(self, session) -> bool:
         """After a model-unavailable error, blacklist it and switch models. Returns False if stuck."""
@@ -219,6 +282,13 @@ class Agent:
 
     def _messages(self, session, cfg=None) -> List[dict]:
         cfg = cfg or getattr(session, "config", None) or self.config
+        notes = getattr(session, "pending_notes", None)
+        if notes:
+            joined = "\n".join(n for n in notes if n)
+            notes.clear()
+            if joined:
+                session.messages.append({"role": "user",
+                                         "content": "Note from the user while you work:\n" + joined})
         system = build_agent_system_prompt(
             root=cfg.root,
             model=session.active_model,
@@ -298,11 +368,25 @@ class Agent:
                 self._append_tool(session, tc_id, f"error: unknown tool '{name}'")
                 continue
 
+            # A PreToolUse hook may deny (skip the tool), allow (skip the prompt), or ask (force it).
+            hook_action, hook_reason = self._pre_tool_hook(session, tool, args, cancel_event)
+            if hook_action == "deny":
+                self._append_tool(session, tc_id, f"user declined via hook: {hook_reason or 'no reason given'}")
+                ui.tool_result(name, ToolResult(ok=False, summary=f"denied by hook: {hook_reason}"[:80]))
+                continue
             # Approval policy: auto-approve when the mode/trust allows it, else prompt.
-            if needs_prompt(mode, tool, args, trusted) is None:
+            must_prompt = needs_prompt(mode, tool, args, trusted)
+            if hook_action == "allow":
+                must_prompt = None
+            elif hook_action == "ask":
+                must_prompt = hook_reason or "hook asked for confirmation"
+            if must_prompt is None:
                 if not getattr(tool, "auto_approve", False):
                     ui.auto_approved(tool, args)  # meta tools render their own output
             else:
+                from .hooks import notify
+
+                notify(session, "approval", f"{name} needs approval: {must_prompt}")
                 approval = ui.approve(tool, args, ctx)
                 if approval.decision == Decision.ABORT:
                     self._append_tool(session, tc_id, "user aborted the operation")
@@ -330,6 +414,7 @@ class Agent:
                 result = ToolResult.fail(f"tool crashed: {exc}")
 
             self._handle_result(session, name, result, ui)
+            self._post_tool_hook(session, tool, args, result)
             payload = result.content if result.ok else f"ERROR: {result.error}"
             self._append_tool(session, tc_id, payload or "(no output)")
         return None

{scootcli-0.2.0 → scootcli-0.4.0}/src/scootcli/auth.py

@@ -43,14 +43,19 @@ def status_rows(config) -> List[dict]:
     default = registry.default_provider_name(config)
     rows = []
     for spec in registry.all_specs():
-        rows.append({
+        url = registry.base_url_for(spec)
+        row = {
             "name": spec.name,
             "source": key_source(spec),
             "required": spec.key_required,
             "configured": is_configured(spec),
             "default": spec.name == default,
-            "base_url": registry.base_url_for(spec),
-        })
+            "base_url": url,
+            "reachable": None,  # only probed for keyless local servers
+        }
+        if not spec.key_required and registry.is_local_url(url):
+            row["reachable"] = registry.reachable(url)
+        rows.append(row)
     return rows
 
 

{scootcli-0.2.0 → scootcli-0.4.0}/src/scootcli/cli.py

@@ -59,6 +59,8 @@ def _build_parser() -> argparse.ArgumentParser:
                         help="Don't inject the repo map (git + file tree) into the agent prompt.")
     parser.add_argument("--no-labels", action="store_true",
                         help="Hide the role labels/gutters (❯ you / ⏺ scoot) in the REPL transcript.")
+    parser.add_argument("--headless", action="store_true",
+                        help="Line-delimited JSON on stdin/stdout instead of the REPL (see docs/headless-protocol.md).")
     parser.add_argument("--no-logo", action="store_true",
                         help="Hide the mascot (launch banner art + status-bar face). Persist with /logo off.")
     parser.add_argument("--no-emoji", action="store_true",
@@ -141,9 +143,30 @@ def _run_once(config: Config, pool: ProviderPool, prompt: str, as_json: bool, re
     from .agent import Agent
     from .repl import ReplSession, ReplUI
 
+    from .providers.registry import readiness
+
+    ready, message = readiness(config)
+    if not ready:  # fail fast with guidance instead of a connection error after retries
+        if as_json:
+            print(_json.dumps({"status": "error", "model": "", "steps": 0, "content": "",
+                               "error": message, "usage": {}}, indent=2))
+        else:
+            eprint(color(message, "yellow"))
+        return 1
     session = ReplSession(config, pool)
     if resume is not None:
         session.apply_record(resume)
+    from .hooks import Hooks, session_event, submit_prompt
+
+    session.hooks = Hooks(config.root)
+    session_event(session, "SessionStart", source="resume" if resume is not None else "startup")
+    submitted = submit_prompt(session, prompt)
+    if submitted is None:
+        reason = getattr(session, "hook_block_reason", "") or "a UserPromptSubmit hook blocked it"
+        eprint(color(f"⏹ prompt not sent: {reason}", "yellow"))
+        session_event(session, "SessionEnd", reason="blocked")
+        return 1
+    prompt = submitted
     # Fold any dropped image paths into the prompt (best-effort; no-op when none/disabled).
     try:
         from .vision import fold_images_into_text
@@ -156,6 +179,7 @@ def _run_once(config: Config, pool: ProviderPool, prompt: str, as_json: bool, re
     agent_config = config.override(stream=False) if as_json else config
     outcome = Agent(agent_config, pool).run_turn(session, ReplUI(), threading.Event())
     session.autosave()  # persist so `scoot -c` can continue this conversation
+    session_event(session, "SessionEnd", reason=outcome.status)
 
     if as_json:
         print(_json.dumps({
@@ -194,7 +218,6 @@ def _cmd_auth(config: Config, pool: ProviderPool, words: List[str]) -> int:
 
 def _interactive(pool: ProviderPool, resume=None) -> int:
     """Launch the persistent REPL (banner, live status, ESC-interrupt, slash-commands)."""
-    from .auth import is_configured, missing_key_hint
     from .repl import Repl
 
     config = pool.config
@@ -205,12 +228,8 @@ def _interactive(pool: ProviderPool, resume=None) -> int:
 
         resume = sessions.latest_for_root(str(config.root))
 
-    try:
-        spec = pool.spec
-        if not is_configured(spec):  # first-run onboarding: guide, but still open the REPL
-            eprint(color(f"No API key for {spec.name}: {missing_key_hint(spec)}", "yellow"))
-    except ScootError as exc:
-        eprint(color(f"⚠ {redact(str(exc))}", "yellow"))
+    # First-run onboarding happens inside the REPL (banner + a setup block), because anything printed
+    # here would be wiped by the screen clear the REPL does on start.
     return Repl(config, pool, resume=resume).run()
 
 
@@ -260,6 +279,13 @@ def main(argv: Optional[List[str]] = None) -> int:
 
         prompt = _resolve_prompt(args)
         resume = _resolve_resume(config, args)
+        if args.headless:
+            if prompt is not None:
+                eprint(color("--headless takes prompts on stdin, not as an argument.", "yellow"))
+                return 2
+            from .headless import run_headless
+
+            return run_headless(config.override(panel=False, dock=False, logo=False), pool, resume=resume)
         if prompt is not None:
             return _run_once(config, pool, prompt, args.json, resume=resume)
         return _interactive(pool, resume=resume)

{scootcli-0.2.0 → scootcli-0.4.0}/src/scootcli/commands/__init__.py

@@ -51,6 +51,8 @@ def load_builtins() -> None:
     from . import verbosity as _verbosity  # noqa: F401
     from . import copy as _copy  # noqa: F401
     from . import logo as _logo  # noqa: F401
+    from . import route as _route  # noqa: F401
+    from . import hooks as _hooks  # noqa: F401
 
     _loaded = True
 

{scootcli-0.2.0 → scootcli-0.4.0}/src/scootcli/commands/auth.py

@@ -24,8 +24,10 @@ def _show(session) -> None:
     print(color("providers:", "bold"))
     for row in rows:
         name = row["name"] + ("  (default)" if row["default"] else "")
-        if not row["required"]:
-            state = color("no key needed", "gray")
+        if not row["required"] and row.get("reachable") is False:
+            state = color("not running (ollama serve; install from https://ollama.com)", "yellow")
+        elif not row["required"]:
+            state = color("no key needed" + (", running" if row.get("reachable") else ""), "gray")
         elif row["source"]:
             state = color(f"key from {row['source']}", "green")
         else:
@@ -67,6 +69,7 @@ def _set(session, name: str) -> None:
     if pool is not None and hasattr(pool, "_providers"):
         pool._providers.pop(name, None)  # rebuild with the new key on next use
     print(color(f"✔ {name} key saved to {path} (owner-only).", "green"))
+    _after_change(session)
 
 
 def _clear(session, name: str) -> None:
@@ -78,6 +81,7 @@ def _clear(session, name: str) -> None:
         print(color(f"forgot the saved {name} key.", "green"))
     else:
         print(color(f"no saved {name} key.", "gray"))
+    _after_change(session)
     pool = getattr(session, "provider", None)
     if pool is not None and hasattr(pool, "_providers"):
         pool._providers.pop(name, None)
@@ -88,6 +92,20 @@ def _clear(session, name: str) -> None:
         print(color(f"  {missing_key_hint(spec)}", "gray"))
 
 
+def _after_change(session) -> None:
+    """A key came or went: the default provider may have changed, so re-resolve and re-check."""
+    try:
+        if session.model.lower() in ("default", "auto"):
+            session.active_model = session.resolved_model()
+        session._available = None  # the model list depends on which providers are configured
+        if session.refresh_readiness():
+            print(color(f"ready: {session.active_model}", "gray"))
+        else:
+            print(color(session.setup_message, "yellow"))
+    except Exception:
+        pass
+
+
 def _run(session, args: str):
     words = (args or "").split()
     if not words:

scootcli-0.4.0/src/scootcli/commands/hooks.py

@@ -0,0 +1,37 @@
+"""/hooks — list the configured hooks and what they did last."""
+
+from __future__ import annotations
+
+from ..hooks import EVENTS, enabled, global_path, project_path
+from ..rendering import color
+from . import register
+from .base import SlashCommand
+
+
+def _run(session, args: str):
+    hooks = getattr(session, "hooks", None)
+    if (args or "").strip() == "reload" and hooks is not None:
+        hooks.reload()
+        print(color("hooks reloaded.", "gray"))
+    print(color("hooks:", "bold"))
+    if not enabled():
+        print(color("  disabled by SCOOT_HOOKS=0", "yellow"))
+    root = getattr(getattr(session, "config", None), "root", ".")
+    print(color(f"  files: {project_path(root)} (project), {global_path()} (global)", "gray"))
+    if hooks is None or not hooks.config:
+        print(color("  none configured", "gray"))
+    else:
+        for event in EVENTS:
+            for entry in hooks.config.get(event, []):
+                matcher = f"  [{entry['matcher']}]" if entry.get("matcher") else ""
+                for hook in entry.get("hooks", []):
+                    print(f"  {color(event, 'cyan')}{matcher}  {hook.get('command', '')}")
+        if hooks.history:
+            print(color("  recent:", "gray"))
+            for r in hooks.history[-8:]:
+                detail = f"  {r.detail[:60]}" if r.detail else ""
+                print(f"    {r.event:<16} {r.outcome:<8} {r.seconds:>5.2f}s  {r.command[:40]}{detail}")
+    print(color("  usage: /hooks [reload]", "gray"))
+
+
+register(SlashCommand("hooks", "list configured hooks and recent results", _run, usage="[reload]"))