@nanobpm/nano-coder 0.34.0 → 0.36.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +107 -5
  2. package/package.json +5 -5
package/README.md CHANGED
@@ -18,7 +18,8 @@ cargo install nano-coder # or build from source
18
18
  - **Providers**: OpenAI-compatible and Anthropic endpoints (remote or local), selected per model as `provider/model`, with retry/backoff
19
19
  - **Tool Calling**: Agent can invoke registered tools during conversation, including a real `bash` tool with timeouts and bounded output
20
20
  - **Sessions**: Append-only JSONL session logs with resume and input-ID deduplication
21
- - **Lifecycle Hooks**: 6 hook events for observing/intercepting agent behavior
21
+ - **Lifecycle Hooks**: 6 internal hook events for observing agent behavior, plus
22
+ Claude Code–compatible external user hooks loaded from `.claude/settings.json`
22
23
  - **Configuration**: TOML-based config file at `~/.config/nano-coder/config.toml`
23
24
  - **Commands**: `/help`, `/compact`, `/context`, `/verbosity`, `/settings`, `/tools`, `/skills`, `/queue`, `/restart`, `/exit`
24
25
  - **Streaming output**: answers stream in, thinking shows collapsed (Ctrl-O expands it), tool calls show inline
@@ -139,7 +140,8 @@ src/
139
140
  ├── main.rs # Single binary entry point (interactive + ACP modes)
140
141
  ├── agent.rs # Agent core: conversation management, tool execution loop
141
142
  ├── acp.rs # ACP JSON-RPC protocol handler
142
- ├── hooks.rs # Lifecycle hook registry and event system
143
+ ├── hooks.rs # Internal (observe-only) lifecycle hook registry and events
144
+ ├── claude_hooks.rs # External Claude Code–compatible user hooks engine
143
145
  ├── tools.rs # Tool registration and dispatch system
144
146
  ├── llm.rs # Provider-neutral messages and the async LLMClient trait
145
147
  ├── providers/ # Provider registry + presets, HTTP transport with retries
@@ -181,7 +183,14 @@ Mode selection: `--acp` flag enables ACP headless mode; default is interactive C
181
183
 
182
184
  ## Lifecycle Hooks
183
185
 
184
- The harness exposes 6 lifecycle hook events:
186
+ nano-coder has two hook systems.
187
+
188
+ ### Internal hooks (observe-only)
189
+
190
+ The harness exposes 6 internal lifecycle hook events for in-process Rust
191
+ callbacks. These are **observe-only**: a callback can inspect the event payload
192
+ (for logging, metrics, debugging) but cannot block, modify, or redirect the
193
+ agent. They are registered programmatically against `agent.hooks()`.
185
194
 
186
195
  | Hook | When it fires |
187
196
  |------|---------------|
@@ -192,6 +201,36 @@ The harness exposes 6 lifecycle hook events:
192
201
  | `before_tool_call` | Before executing a tool |
193
202
  | `after_tool_call` | After tool execution completes |
194
203
 
204
+ ### External user hooks (Claude Code–compatible)
205
+
206
+ nano-coder also runs **external user hooks** that follow the
207
+ [Claude Code hooks protocol](https://docs.claude.com/en/docs/claude-code/hooks),
208
+ so existing Claude Code hook configurations work unchanged. These are loaded,
209
+ in order, from:
210
+
211
+ 1. `[hooks]` in nano-coder's own user config (`config.toml`), in Claude's structure
212
+ 2. `~/.claude/settings.json` (your Claude Code user settings; disable with `claude_user_hooks = false`)
213
+ 3. `<project>/.claude/settings.json` (project settings, committed)
214
+ 4. `<project>/.claude/settings.local.json` (project-local, git-ignored)
215
+
216
+ Each hook is a `command` that nano-coder runs as a subprocess, passing the
217
+ event payload as JSON on stdin and interpreting its exit code and (optional)
218
+ JSON stdout per Claude's protocol. Hooks can **block** a tool call or prompt,
219
+ **modify** a tool's input, or **inject additional context**. nano-coder
220
+ translates its tool names (`bash`→`Bash`, `read_file`→`Read`, `write_file`→
221
+ `Write`, `edit_file`→`Edit`, `grep`→`Grep`, `glob`→`Glob`) and the `file_path`/
222
+ `path` argument so Claude-authored matchers and scripts match correctly.
223
+
224
+ Supported events: `SessionStart`, `UserPromptSubmit`, `PreToolUse`,
225
+ `PostToolUse`, and `Stop`. A `PreToolUse` hook that fails (crashes, times out,
226
+ or exits non-zero) **fails closed** and blocks the tool call; failures in other
227
+ events are non-blocking.
228
+
229
+ Run `/hooks` at the prompt to list the loaded hooks, which files they came
230
+ from, and any that were skipped (e.g. unsupported events reserved for later
231
+ phases). Disable them with `--no-hooks`, or granularly via the
232
+ `disable_hooks`, `disable_project_hooks`, and `claude_user_hooks` settings.
233
+
195
234
  ## Built-in Tools
196
235
 
197
236
  - `get_time` - Get current date and time
@@ -306,7 +345,7 @@ model where it may write.
306
345
  Typing `/` at the prompt lists the commands under it, and each further character narrows the
307
346
  list. Tab completes the command, or the part all matches share. Esc hides the list. The
308
347
  list is built from the same table as `/help` (`src/commands.rs`). Commands with a known
309
- argument set (`/model`, `/mode`, `/verbosity`) get the same treatment for their first
348
+ argument set (`/model`, `/mode`, `/verbosity`, `/thinking`) get the same treatment for their first
310
349
  argument: a type-ahead list narrows as you type and Tab completes it.
311
350
 
312
351
  - `/help` - Show available commands
@@ -333,12 +372,14 @@ argument: a type-ahead list narrows as you type and Tab completes it.
333
372
  - `/skills` - List the skills the agent can load, where each lives, and any loading warnings
334
373
  - `/plan` - Show the agent's task plan with all notes
335
374
  - `/memory [forget ID]` - List cross-session memories with their ids, or delete one by id (see [Memory](#memory))
375
+ - `/hooks` - List the loaded external user hooks (from `.claude/settings.json` and friends), the files they came from, and any skipped entries (see [Lifecycle Hooks](#lifecycle-hooks))
336
376
  - `/queue [list|add text|remove N...|edit N text|clear]` - Show or edit the queued messages. Works while a turn runs, so a queued message can be removed or rewritten before it is sent.
337
377
  - `/model [provider/model]` - Show the current model and pick a new one. The list starts with the last four models you used (the current one marked; the previous one highlighted, so `/model` then Enter switches back), then the providers: pick a provider to scroll its model list (Esc steps back). With an argument, switches directly (conversation is kept). Typing `/model ` shows a type-ahead of the current model, recently used models, and each configured provider's default model; Tab completes (a bare provider name completes to its default model). Recently used models are kept in `~/.local/share/nano-coder/recent-models.json`
338
378
  - `/mode [normal|plan|auto]` - Show or set the agent mode (Shift+Tab cycles it, at the prompt or mid-turn):
339
379
  - **normal** - full tools; reaching a positive turn cap asks whether to keep going
340
380
  - **plan** - read-only: mutating tools (`bash`, `write_file`, `edit_file`) are gated, only analysis and output
341
381
  - **auto** - no turn cap; a `question` left unanswered for 15s is answered with "the user is away from the keyboard, make the best decision you can"
382
+ - `/thinking [level|default|off|reset]` - Show the thinking level in use and the levels the current model takes, or set one for this session (`reset` goes back to the configured level). See [Thinking](#thinking)
342
383
  - `/providers` - List providers, endpoints and whether their API key is available
343
384
  - `/session` - Show the session ID and log path
344
385
  - `/trajectory` - Show this session's trajectory turn by turn: user input, thinking, answers, tool calls and results, tokens and timings. Each message row is labelled with its `#N` session-log ID, the same ID `history_read` and smart-compaction summaries use (compaction and crash-recovered input rows have no `#N`, as they aren't cited that way). When it doesn't fit on the screen it opens in your pager (`$PAGER`, default `less`) — but only at an idle prompt with the frame renderer: invoked mid-turn (while a turn runs) or under the legacy renderer it prints inline instead. `/trajectory --json` or `/trajectory --markdown` prints an export instead; `nano-coder --trajectory SESSION_ID [--json|--markdown]` does the same for any saved session
@@ -542,6 +583,63 @@ top-level `temperature` just doesn't apply to them. Anthropic accepts 0 to 1, so
542
583
  value is sent as 1, with a warning. `/context` shows the temperature in use and where it
543
584
  comes from, and `/settings` edits it for the current model, its provider, or all models.
544
585
 
586
+ ### Thinking
587
+
588
+ `thinking` sets how much the model reasons before it answers: `"default"` sends nothing
589
+ (the model decides), `"off"` turns thinking off, and a level such as `"low"`, `"medium"`,
590
+ `"high"`, `"xhigh"` or `"max"` asks for that much. Like `temperature`, it can be set for all
591
+ models, one provider or one model, and `/thinking LEVEL` overrides them for the session:
592
+
593
+ ```toml
594
+ thinking = "medium" # all models that support it
595
+
596
+ [providers.anthropic.models."claude-opus-4-7"]
597
+ thinking = "xhigh" # this model only
598
+ ```
599
+
600
+ A model only gets levels it supports. They come from, in order: `thinking_levels` on the
601
+ model or provider; what the endpoint reports for the model; and a built-in table
602
+ of Claude (3.7 Sonnet and later) and OpenAI reasoning models (GPT-5 and later, o1/o3/o4).
603
+ Endpoints that report levels:
604
+
605
+ - **GitHub Copilot:** `/models` lists each model's levels, read with the same request as its
606
+ context window.
607
+ - **Ollama:** a model with the `thinking` capability (`/api/show`) gets `off`, `low`,
608
+ `medium` and `high`. Ollama refuses a level for a model without it, so none is sent then.
609
+ - **llama.cpp:** the loaded model's chat template (`/props`) decides. A template with an
610
+ `enable_thinking` switch (Qwen 3 and the like) gets `off` and `on`, and any named level
611
+ turns thinking on; a template that takes `reasoning_effort` (gpt-oss) gets `low`, `medium`
612
+ and `high`.
613
+
614
+ Ollama and llama.cpp are recognized however the provider is named, the same way as for the
615
+ context window. For other models, list the levels yourself:
616
+
617
+ ```toml
618
+ [providers.together.models."deepseek-r1"]
619
+ thinking_levels = ["low", "medium", "high"] # add "off" if thinking can be turned off
620
+ ```
621
+
622
+ A level the model lacks is moved to the nearest one it has (the highest below it, else the
623
+ lowest), and a model with no known levels is sent nothing. A setting for the provider, the
624
+ model or the session warns when it is adjusted or ignored; the top-level `thinking` doesn't
625
+ warn, since it applies to every model.
626
+
627
+ How the level is sent depends on the API: `reasoning_effort` (Chat Completions, Ollama
628
+ included; Ollama ignores its native `think` flag on `/v1`), `chat_template_kwargs` for
629
+ llama.cpp (`enable_thinking`, or `reasoning_effort` for templates that take a level; it
630
+ ignores the top-level `reasoning_effort`),
631
+ `reasoning.effort` (Responses), and for Anthropic Messages adaptive thinking with
632
+ `output_config.effort`, or on Claude 3.7 to 4.5 a fixed `budget_tokens` (1024 for minimal, then
633
+ 2048, 8192, 16384, 32768, 65536 up to max). The budget has to stay below `max_tokens`, so raise
634
+ `max_tokens` to use a large one. Anthropic takes no custom temperature while thinking, so
635
+ none is sent then. A matching key in the provider's `extra_body` (`reasoning_effort`, `reasoning`,
636
+ `think`, `chat_template_kwargs`, `thinking`, `output_config`) is sent instead, with a warning; the
637
+ configured level is then reported as overridden (not as sent), since the override's value is what
638
+ reaches the wire. The status bar shows
639
+ `think LEVEL` while a level is sent, `/context` shows it with where it comes from,
640
+ `/settings` sets it for the current model, its provider or all models (picking from the
641
+ levels the model supports), and the session log records it for each reply.
642
+
545
643
  Other per-provider fields: `replay_reasoning`, `max_tokens_param` (`max_tokens`, or `max_completion_tokens`
546
644
  which is the `openai` default), `retry_initial_backoff_ms`, `retry_max_backoff_ms` and
547
645
  `retryable_statuses`.
@@ -940,7 +1038,7 @@ agent.tools().register(tool_def, Box::new(|args| {
940
1038
 
941
1039
  The model sees a JSON string result as plain text and any other value as serialized JSON.
942
1040
 
943
- ### Adding Hooks
1041
+ ### Adding internal (observe-only) hooks
944
1042
 
945
1043
  ```rust
946
1044
  agent.hooks().register(HookEvent::BeforeToolCall, Box::new(|ctx| {
@@ -949,6 +1047,10 @@ agent.hooks().register(HookEvent::BeforeToolCall, Box::new(|ctx| {
949
1047
  }));
950
1048
  ```
951
1049
 
1050
+ These callbacks observe only; to block, modify, or add context to a tool call
1051
+ or prompt, use the external Claude-compatible user hooks described under
1052
+ [Lifecycle Hooks](#lifecycle-hooks).
1053
+
952
1054
  ### Custom LLM Client
953
1055
 
954
1056
  Implement the async `LLMClient` trait (or add a `ProviderKind` in `src/providers/`):
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@nanobpm/nano-coder",
3
- "version": "0.34.0",
3
+ "version": "0.36.0",
4
4
  "description": "A 6MB coding agent. Run a fleet on your laptop.",
5
5
  "license": "Apache-2.0",
6
6
  "repository": {
@@ -31,9 +31,9 @@
31
31
  "node": ">=18"
32
32
  },
33
33
  "optionalDependencies": {
34
- "@nanobpm/nano-coder-darwin-arm64": "0.34.0",
35
- "@nanobpm/nano-coder-darwin-x64": "0.34.0",
36
- "@nanobpm/nano-coder-linux-arm64": "0.34.0",
37
- "@nanobpm/nano-coder-linux-x64": "0.34.0"
34
+ "@nanobpm/nano-coder-darwin-arm64": "0.36.0",
35
+ "@nanobpm/nano-coder-darwin-x64": "0.36.0",
36
+ "@nanobpm/nano-coder-linux-arm64": "0.36.0",
37
+ "@nanobpm/nano-coder-linux-x64": "0.36.0"
38
38
  }
39
39
  }