samagotchi 0.2.0

data/docs/guardrails.md

@@ -0,0 +1,218 @@
+# Guardrails
+
+Every tool call the model makes passes one check before it runs, in both
+loops (native and chat hosts). The verdict is **allow**, **ask** or
+**deny**; the strictest vote wins, and a deny can't be undone by a later
+voter.
+
+Who votes, in order:
+
+1. `before_tool_call` hooks (Ruby; see [Hooks](hooks.md#guardrails-from-a-hook)).
+2. Core checks: a required guardrail that failed to load, then protected paths.
+3. YAML rules: `config.yml`'s `guardrails:` section, then installed bundles' rule files (by bundle name).
+
+The UI shows the tool line first, then the approval under it.
+
+## Ask
+
+The REPL, the attached TUI and the web show what would run, where and why:
+
+```
+Approve tool call?
+! execute: git push origin main
+  in /home/me/app (repo app, branch main)
+  why: git push publishes commits (rule git-push, bundle guardrails)
+  1) Allow once
+  2) Allow this call for the session
+  3) Allow this call in this repo
+  4) Allow rule git-push in this repo
+  5) Deny
+```
+
+In a terminal, answer with a number, the exact label, `y` (Allow once) or `n`
+(Deny); add `; reason` to tell the model why (`n; open a PR instead`). An empty
+answer, Ctrl-C, the web's Deny button or a cancelled turn deny it. The prompt stays open during turns: when the question comes up it turns
+into a yellow `? `, with the call and the options listed under it; only a line
+submitted there answers it (never one typed before), and what you had typed comes back
+once it closes. On a short terminal the list shrinks (the hint row, then the `in`/`why`
+lines, then the header go, then the options fold onto fewer rows). Once answered, one
+line stays in the scrollback: `! execute: git push origin main → Allow once`.
+
+Who answers:
+
+- REPL (`chi --no-shared`, `-p` without `--non-interactive`): at the `? ` prompt.
+- A shared session's worker: any attached TUI or web page. With none attached,
+  the approval waits (in the session file) and shows on attach.
+- `-p … --non-interactive`: nobody; the call is denied ("No one to approve it
+  (non-interactive run)").
+
+The model gets one line on a deny. A rule's or hook's deny reads
+`[execute] Error: denied by guardrail (rule git-push, bundle guardrails): git push publishes commits. The user was not asked. Do not retry it or reach the same result another way; ask the user how to proceed.`
+When the user picks Deny on an ask, it leads with the user's answer:
+`[execute] Error: The user declined this call: "open a PR instead". It needed approval (rule git-push, bundle guardrails): git push publishes commits. Do not retry it or reach the same result another way; ask the user how to proceed.`
+
+## Approvals
+
+Allowing beyond "once" is stored in `$XDG_STATE_HOME/samagotchi/guardrails/approvals.json`
+(default `~/.local/state/samagotchi/guardrails/`):
+
+| Scope | Allows |
+|---|---|
+| session | this exact call (tool + command, or paths) in this session |
+| repo | this exact call in this repo (the cwd outside a repo), any session |
+| rule | anything this rule asks about in this repo |
+
+A stored approval only relaxes an ask; a deny rule is never approvable.
+A file that doesn't parse is moved aside to `approvals.json.corrupt-<UTC time>`
+with one warning, and chi starts with no stored approvals (more asks, nothing lost).
+`/guardrails` lists the rules and approvals; `/guardrails revoke N` removes one.
+The file tools can't write the store.
+
+## Protected paths
+
+Built in, for `write`, `edit` and `memory_write` (symlinks resolved):
+
+- deny: the approval store's dir, and installed bundles (`memories/.bundles/`);
+- ask (once or for the session): `config.yml` and the plain hooks dir.
+
+`execute` can still reach them; the guardrails bundle asks about shell
+commands that name them.
+
+## Rules in config.yml
+
+```yaml
+guardrails:
+  enabled: true              # false: no rules, and hooks' asks are dropped (a deny still applies)
+  rules:
+    - id: git-push
+      tool: shell            # execute + task_create; or a tool name, a glob, or a list
+      command: '\bgit\s+push\b'   # Ruby regex on the command
+      verdict: ask           # ask | deny
+      reason: git push publishes commits
+      scopes: [once, session, repo]   # optional; default all four
+    - id: write-outside-repo
+      tool: [write, edit]
+      path: outside_repo     # or a glob: "**/.git/hooks/**", "/etc/**", "config/*.yml"
+      verdict: ask
+      reason: writes outside the repository
+```
+
+A tool name may be a glob, so one rule covers a plugin's tools (an MCP server's,
+say): `tool: "mcp_*"` or `tool: ["mcp_{git,gh}_*", web_fetch]` (`*`, `?`, `[…]` and
+`{a,b}`, matched with `File.fnmatch`). `/guardrails` lists the glob as given.
+A plugin tool whose `targets:` name no command or path (an MCP tool) is asked
+about with its arguments (`mcp_x_sum: a=20 b=22`), and an approval of "this
+call" is keyed by them.
+
+```yaml
+    - id: mcp-ask
+      tool: "mcp_*"          # every MCP tool (the mcp bundle's mcp_<server>_<tool>)
+      verdict: ask
+      reason: an MCP server's tool
+```
+
+All the fields a rule gives must match. Absolute and `**/` globs match the
+resolved path; other globs match the path relative to the repo root. Paths
+resolve the way the tools resolve them (against the cwd; `~` expanded).
+
+To switch off single rules (a bundle's, say) without editing its files, list
+them under `disable:`. A plain id switches off every rule with that id; `bundle:id`
+only that bundle's:
+
+```yaml
+guardrails:
+  disable: [git-rebase, guardrails:git-push]
+```
+
+`/guardrails` marks them `disabled (guardrails.disable)` and names entries that
+match no rule. `disable:` only removes rules; hooks and the core checks still vote.
+
+Rules load when chi starts (a long-running worker picks up changes after its
+next start). A rule that doesn't parse (an unknown key, a bad regex, no
+verdict, a `disable:` that isn't a list of ids) makes chi **deny every tool call** and say why, rather than run
+without it.
+
+## The guardrails bundle
+
+```sh
+chi bundle install guardrails
+```
+
+installs a default rule set plus a short memory telling the model not to
+route around a deny. It asks before `git push`, `reset --hard`, `clean -f`,
+`branch -D`, `rebase`, `filter-branch`/`filter-repo`; `rm -rf` on `/`, `~`,
+`$HOME` or `..` paths; `curl … | sh` and `base64 -d … | sh`; writes outside the
+repo; and shell commands that name chi's config, hooks or guardrails or
+`.git/hooks`. It denies writes into `.git/hooks`. The rules are in
+`lib/samagotchi/bundles/guardrails/guardrails/rules.yml`.
+
+A bundle ships rules as `guardrails/*.yml` (the same `rules:` shape). Install
+records each file's sha256; a file changed afterwards, missing, or not parsing
+denies every call until the bundle is reinstalled.
+
+## The known-names bundle
+
+```sh
+chi bundle install known-names
+```
+
+installs one `before_tool_call` hook and a short memory. A local model that
+once misspells a name inside a path (`jonathandoe` → `jonathndoe`)
+keeps copying the wrong spelling from its context, and every call after
+that fails. The hook knows the right names and compares strings: the
+user's home folder name, login (`$USER`), git `user.name` words and email
+local part, the repo folder name, and any names from config. A token in a
+call's command, `cwd` or paths (never a write's content) that is within one
+edit of a known name shorter than 10 characters, or two edits of a longer
+one, is a near miss. Tokens and names shorter than `min_length` (6) are
+skipped, as is a token that equals another known name.
+
+By default (`mode: reject`) the call is denied with advice in place of the
+usual tail, so the model retries it corrected:
+
+```
+[execute] Error: denied by guardrail (hook known_names, bundle known-names): "johndeo" in the command is 1 edit away from the known name "johndoe". The user was not asked. Retry with "johndoe". If "johndeo" is really what you meant, say so to the user instead of retrying.
+```
+
+and the user sees one line: `known-names> rejected execute: "johndeo" looks like "johndoe"`.
+
+```yaml
+bundles:
+  known-names:
+    names: [jonathandoe]      # protected besides the derived ones
+    mode: reject              # reject | correct | ask
+    derive: [home, user, git, repo]
+    ignore: [jondoe]          # a real name that is near a protected one
+    min_length: 6
+    max_distance: 2           # default: 1 under 10 characters, else 2
+```
+
+`mode: correct` rewrites the call (whole tokens, everywhere they appear) and
+says so; `mode: ask` shows the call with three choices, *Correct it and
+run*, *Run as is*, *Deny*; with no one to ask (`--non-interactive`) or a
+dismissed question it rejects. A real near name (a folder `jondoe` next to
+user `johndoe`, a login one letter from another) is caught too: list it under
+`ignore:`. The hook is `on_error: log`: a bug in it warns and lets the call
+through. As with every bundle hook, a running worker picks it up after its
+next start.
+
+The system prompt names the home directory once, with the advice to write
+it as `~` or `$HOME`, so the model rarely has to spell it.
+
+## Failing closed
+
+- A config hook with `required: true`, or a bundle `before_tool_call` hook with
+  `on_error: fail_closed`, that fails to load (missing, syntax error, or for a
+  bundle hook a sha256 that differs from the installed one) makes chi deny
+  every tool call. One that raises when called denies that call.
+- Other hooks stay fail-open; a load failure is a warning.
+- Every load failure is shown once, at the start of the first turn
+  (`guardrails> …` in the terminal, a red line on the web).
+
+## Limits
+
+Text matching on shell commands stops accidents, not a model set on getting
+around it: `sh -c`, base64, a script written earlier, `git -C` variants and
+aliases can get past a regex. `!cmd` lines typed by you are not checked. The only
+real defence against an adversarial model is isolation (a sandbox, a git
+identity without push rights).

data/docs/hooks.md

@@ -0,0 +1,309 @@
+# Hooks
+
+Samagotchi supports pluggable Ruby hooks that fire at key lifecycle points
+during agent turns. Hooks let you add external tooling (CI checks, logging,
+analytics) or in-process verification (test gates, policy checks).
+
+A bundle can go further with a plugin: slash commands and tools as well as
+hooks. See [Plugins](plugins.md).
+
+## Configuration
+
+Add a `hooks:` section to your global config file (`~/.config/samagotchi/config.yml`):
+
+```yaml
+hooks:
+  hooks_dir: "~/.config/samagotchi/hooks/"
+  session_start:
+    - path: "analytics.rb"
+      on_error: log
+  before_turn:
+    - path: "audit.rb"
+      on_error: skip
+  after_tool_call:
+    - path: "metrics.rb"
+      on_error: skip
+```
+
+## Plugin Format
+
+Each plugin is a `.rb` file in the hooks directory. The class name must match
+the filename (snake_case → PascalCase):
+
+```ruby
+# ~/.config/samagotchi/hooks/metrics.rb
+class Metrics
+  def call(event)
+    # event is a Hash — you can read or mutate fields
+    tool = event[:tool]
+    output = event[:output]
+    # ... record metrics, log, etc.
+  end
+end
+```
+
+The plugin class must respond to `#call(event)` — duck-typed, no base class required.
+
+## Hook Events
+
+| Event | When it fires | Event payload |
+|-------|--------------|---------------|
+| `:session_start` | First turn of the session | `{ type: :session_start, session_id: "..." }` |
+| `:before_turn` | Before each turn starts | `{ type: :before_turn, session_id: "...", prompt: "..." (nil on a continue), messages: [...] (the history before this turn) }` |
+| `:after_turn` | After a turn completed or was cancelled (not after one that failed) | `{ type: :after_turn, status: "completed" \| "canceled", messages: [...] (the conversation the turn stored; a cancelled or empty turn ends it with a `kind: turn_note` system message, and a context line is `kind: context`, see [sessions.md](sessions.md#notes-a-turn-leaves-for-the-model)) }` |
+| `:before_generation` | Before each LLM API call (both loops) | `{ type: :before_generation, iteration: N }` |
+| `:after_generation` | After LLM returns (both loops) | `{ type: :after_generation, iteration: N, response: "...", messages: [...] (the conversation as sent) }` |
+| `:before_tool_call` | Before tool dispatch (and before `tool_call_started`) | `{ type: :before_tool_call, iteration: N, call: {...}, params: "...", guardrail: Verdict, context: {...}, targets: {...}, blocked: false, block_reason: nil }` |
+| `:after_tool_call` | After tool execution | `{ type: :after_tool_call, iteration: N, tool: "read", output: "..." }` |
+| `:session_end` | After every turn (turn-level lifecycle) | `{ type: :session_end, session_id: "..." }` |
+
+Every event also carries the hook runtime (next section): `hook:` (the label
+of the hook about to run) and the callables `notify:`, `ask_user:`,
+`stop_turn:`.
+
+`messages:` is a **read-only copy**: a frozen array of copied message hashes
+(`{role:, content:, …}`). A hook that mutates it, or its strings, gets
+undefined behaviour. `:before_tool_call` carries no messages (the gate stays
+cheap).
+
+## What a hook can do: the runtime
+
+Besides reading (and, on `:before_tool_call`, voting on) its event, a hook
+can talk to the user through three callables the registry puts on every
+event:
+
+```ruby
+class Watchful
+  def call(event)
+    case event[:type]
+    when :after_generation
+      # One line in the REPL, the attached TUI and the web ("<bundle>> text",
+      # or "hook> text" for a config hook); level: :warn colours it.
+      event[:notify].call("the model repeated itself", level: :warn)
+    when :before_tool_call
+      # A single-select question through the question flow (REPL, attached
+      # TUI, web); returns {selected: [...], freeform:, selected_indices:}
+      # or nil when there is no one to ask (--non-interactive), the
+      # question was dismissed, or the options were not 2-8 strings.
+      answer = event[:ask_user].call(question: "#{event[:call][:name]}: #{event[:params]}\nRun it?",
+                                     options: ["Run", "Deny"], header: "my guard", allow_freeform: false)
+      event[:guardrail].deny!("the user said no") unless answer&.dig(:selected)&.first == "Run"
+    when :before_generation
+      # Cancel the running turn: a warn notice with the reason, then the
+      # turn ends as cancelled (hook). From :before_tool_call it also denies
+      # that call, and the rest of the batch is denied; from :after_turn or
+      # :session_end it does nothing (false).
+      event[:stop_turn].call("too many iterations without progress") if event[:iteration] > 20
+    end
+  end
+end
+```
+
+`event[:hook]` is the label the notices carry: `known_names.rb (bundle
+known-names)` for a bundle hook, `audit.rb (config)` for a config hook,
+`turn hook` for one registered at runtime.
+
+Timing: a notice from `:after_turn` or `:session_end` shows after the turn's
+end line. A question from `:before_tool_call` shows **before** the tool
+line (the gate runs first), so its text should name the call. The notices
+are also logged (`turn` tag, `hook_notice`).
+
+## Settings
+
+A hook class whose `initialize` takes an argument gets its settings: **one
+positional Hash with string keys** (`def initialize(settings = {})`;
+`initialize(**kw)` is not supported). A class whose `initialize` takes none
+is built bare. Defaults belong in the hook.
+
+```yaml
+bundles:                 # per bundle, by name, for its hooks
+  known-names:
+    names: [jonathandoe]
+    mode: reject
+hooks:
+  before_tool_call:
+    - path: my_guard.rb  # a config hook: its entry's settings
+      settings: { threshold: 2 }
+```
+
+Two config entries for the same file with different settings get two
+instances. A running worker reads config at start (restart it after a
+change), as for every hook.
+
+## Error Handling
+
+- `on_error: "skip"` (default): silently ignore hook failures
+- `on_error: "log"`: emit a `warn` message to stderr
+- `required: true` (config hooks): the hook is a guardrail. If it fails to load
+  (missing file, syntax error), chi denies every tool call and says why; if it
+  raises as a `before_tool_call` hook, that call is denied. See
+  [Guardrails](guardrails.md#failing-closed).
+
+A hook that fails to load is reported as a `[samagotchi:hooks]` warning and
+once in the UI.
+
+Hook failures never break the engine loop — each hook is wrapped in its own
+try/catch.
+
+## Runtime Hook Registration
+
+You can also register hooks programmatically during a turn (they are cleared
+automatically after each `run_turn`):
+
+```ruby
+engine = Samagotchi::Engine.new(mode: :assist)
+engine.register_hook(:before_turn) do |event|
+  puts "Turn starting..."
+end
+engine.run_turn(session, "Hello")
+# Hooks cleared automatically — won't fire on the next turn
+```
+
+## Example Plugins
+
+**Logging every tool call:**
+
+```ruby
+# ~/.config/samagotchi/hooks/audit.rb
+class Audit
+  def call(event)
+    return unless event[:type] == :after_tool_call
+    puts "[audit] #{event[:tool]} → #{event[:output][0..100]}"
+  end
+end
+```
+
+**Tracking tool call counts:**
+
+```ruby
+# ~/.config/samagotchi/hooks/tool_counter.rb
+class ToolCounter
+  def initialize
+    @counts = Hash.new(0)
+    @mutex = Mutex.new
+  end
+
+  def call(event)
+    return unless event[:type] == :after_tool_call
+    @mutex.synchronize { @counts[event[:tool]] += 1 }
+  end
+
+  def report
+    @mutex.synchronize { @counts.dup }
+  end
+end
+```
+
+<a id="guardrails-from-a-hook"></a>
+**Guardrails from a hook (allow / ask / deny):**
+
+```ruby
+# ~/.config/samagotchi/hooks/safety.rb
+class Safety
+  def call(event)
+    return unless event[:type] == :before_tool_call
+    command = event[:targets][:command].to_s   # execute / task_create
+    if command.include?("rm -rf /")
+      event[:guardrail].deny!("dangerous command denied by policy")
+    elsif event[:targets][:outside_repo]
+      event[:guardrail].ask!("writes outside the repo", scopes: %w[once session])
+    end
+  end
+end
+```
+
+`event[:guardrail]` is the call's verdict. `deny!(reason, rule: nil, source: nil, advice: nil)`
+and `ask!(reason, scopes: nil, rule: nil, source: nil)` vote; the strictest
+vote wins (deny > ask > allow) and a vote never relaxes it, so a later hook
+can't undo a deny. An ask goes to the user (see [Guardrails](guardrails.md#ask)).
+`advice:` replaces the fixed "Do not retry it…" tail of the deny text with
+the voter's own (a guard that wants the model to retry a corrected call:
+`Retry with "…".`).
+
+`event[:context]` is `{cwd:, repo_root:, branch:, session_id:, interface:, origin:}`
+(`interface` is `:repl`, `:worker` or `:non_interactive`). `event[:targets]` is
+what the call acts on, resolved as the tools resolve it:
+`{command:, paths:, cwd:, repo_root:, outside_repo:}`.
+
+The older flag still works: `event[:blocked] = true` with an optional
+`event[:block_reason]`. It is folded into the verdict after each hook (so it
+is sticky too), and the model gets `[<tool>] Error: blocked by guardrail: <reason>`
+(default reason `blocked by hook`). A verdict's deny reads
+`[<tool>] Error: denied by guardrail (<rule or hook>): <reason>. … Do not retry it …`
+(after a user's Deny on an ask: `[<tool>] Error: The user declined this call… It needed approval (<rule or hook>): <reason>. …`).
+Either way the activity status is `blocked`, and `:after_tool_call` still fires.
+Only `:before_tool_call` votes.
+
+**Mutating params (legacy):**
+
+```ruby
+# ~/.config/samagotchi/hooks/safety_legacy.rb
+class SafetyLegacy
+  def call(event)
+    return unless event[:type] == :before_tool_call
+    tool = event[:call][:name]
+    if tool == "execute" && event[:call][:content]&.include?("rm -rf /")
+      event[:call][:content] = "echo 'Safety check: dangerous command blocked'"
+    end
+  end
+end
+```
+
+Note: `:before_tool_call` can replace the `:call` hash to change what runs; `tool_call_started` (what the UIs show) and the rules see the final call.
+
+## Bundle Hooks (unified workflow bundle)
+
+Bundles can ship executable guardrails alongside memories. A bundle with hooks lives as a directory with a `hooks/` subdirectory (flat, basename-keyed):
+
+```
+my-bundle/
+  manifest.yml
+  identity.md
+  hooks/
+    guardrails.rb   # class Guardrails; def call(event); ...; end; end
+    audit.rb
+```
+
+`manifest.yml` may carry an optional `hooks:` map (both `files:` and `hooks:` are optional; a bundle may carry only one):
+
+```yaml
+name: code-review-workflow
+version: 1.0.0
+scope: project
+files:
+  identity.md: sha256:abc...
+hooks:
+  guardrails.rb:
+    sha256: 1234...
+    event: before_tool_call
+    on_error: fail_closed   # default for before_tool_call
+    priority: 10
+  audit.rb:
+    sha256: 5678...
+    event: after_tool_call
+    on_error: log
+    priority: 100
+trust_level: reviewed        # reviewed | experimental (default)
+needs: [gh]                  # optional: outside commands the memories use (docs/memory.md#bundles-that-need-outside-commands)
+```
+
+Notes:
+
+- Hook key = basename (flat under `hooks/`). No subdirs in v1.
+- `event` is required for auto-registration; a hook with no event is skipped.
+- `sha256` is integrity (not authenticity). No signing in v1. Install records the sha256 of the copied file; at `Engine.new` a hook whose file differs is not loaded (reinstall the bundle after editing one by hand).
+- Hook code is the bundle author's source of truth: on upgrade, hooks are overwritten; if the installed file was locally modified, a warning is emitted (`was locally modified; overwriting`).
+- A raising `:before_tool_call` guardrail respects `on_error`: `fail_closed` denies the call (fail-closed), `log` warns, `skip` is silent.
+- A `fail_closed` `:before_tool_call` hook is required: if it is missing, fails to load or its sha256 differs, chi denies every tool call until it is fixed.
+- A bundle can also ship YAML rules in `guardrails/*.yml`; see [Guardrails](guardrails.md#the-guardrails-bundle).
+- Ordering: bundle hooks fire by `(priority, bundle_name, hook_name)` (lower priority first), then plain `config.yml` hooks in registration order.
+- Settings: a hook class with `initialize(settings = {})` gets the bundle's section of `config.yml` `bundles:` (see [Settings](#settings)).
+- A bundle can also ship a `plugin.rb` whose `chi.on(event)` blocks are bundle hooks too, next to commands and tools; see [Plugins](plugins.md).
+- Shipped bundles: `chi bundle install guardrails` (rules, see [Guardrails](guardrails.md#the-guardrails-bundle)) and `chi bundle install known-names` (a hook, see [Guardrails](guardrails.md#the-known-names-bundle)), `chi bundle install btw` (a plugin: `/btw`, see [Plugins](plugins.md#the-btw-bundle)), `chi bundle install mcp` (a plugin: tools from MCP servers, see [Plugins](plugins.md#the-mcp-bundle)) and `chi bundle install loop-guard` (a plugin: breaks tool-call loops, see [Plugins](plugins.md#the-loop-guard-bundle)).
+- Installing a bundle executes its hook code at `Engine` startup. Only install bundles you trust, as you would a gem. Hooks are **not** executed at install time (copy-only); they are `module_eval`'d at `Engine.new` inside per-bundle `Samagotchi::Bundles::<name>` namespaces (no top-level `require` collisions). Keep hook files side-effect-free at load time; do work in `#call` — top-level side effects (require, IO, `at_exit`, global assignment) run once per `Engine.new` (class redefinition is idempotent).
+
+Lifecycle:
+
+- `chi bundle install <source>` copies `hooks/*.rb` to `~/.config/samagotchi/memories/.bundles/<name>/hooks/` and persists metadata + `trust_level` + `source_commit` (git HEAD) to provenance.
+- `Engine.new` loads `config.yml` hooks first, then bundle hooks via `Provenance.each_installed_holding_hooks` → `Hooks::BundleLoader.load`. Bundle hooks are process-scoped (they survive the per-turn `clear_hooks`; only plain hooks are cleared). Experimental bundles emit a one-line startup warning.
+- `chi bundle status`, `diff`, `uninstall`, `build` are hook-aware (counts, metadata, removal).

data/docs/internals/background-tasks.md

@@ -0,0 +1,26 @@
+# Background task tools
+
+Samagotchi supports long-running commands in the background through five task tools:
+
+- `task_create`: start a background command and return `task_id` plus `output_path`.
+- `task_get`: fetch current task metadata by id.
+- `task_list`: list all tasks for the current workspace.
+- `task_stop`: stop a running task by id.
+- `task_wait`: wait up to 600 seconds by default for a task to finish.
+
+Recommended workflow:
+
+1. Create a task with `task_create`.
+2. Use `task_wait` once. On timeout it returns the last 10 log lines, avoiding a separate read just to see progress.
+3. For commands with a reliable completion marker, pass `done_pattern` to return when the recent log tail matches it.
+4. Use `task_get` or `task_list` for nonblocking status checks, and `task_stop` if needed.
+
+Behavior:
+
+- Task metadata and output are persisted under `tmp/tasks/`.
+- Task listing is workspace-scoped (current project only).
+- `task_get` returns metadata and `output_path`; use `read` for output contents.
+- `task_wait` accepts `timeout`, `tail_lines` (maximum 100), and `done_pattern` (a regular expression string).
+- `task_create` accepts `env` as a JSON object string for deterministic overrides such as `PATH`; use an absolute interpreter path when that is simpler. Ruby/Bundler isolation variables remain protected.
+
+Work that needs a model, not a shell command, goes to a child chi session instead: `delegate` / `delegate_result` have the same shape (start, then wait) and return only the child's final reply; see [Sessions: Delegating](../sessions.md#delegating).

data/docs/internals/context-telemetry.md

@@ -0,0 +1,36 @@
+# Context status telemetry
+
+The kernel surfaces context-usage telemetry to UI consumers (status line,
+web/SSE clients) as a `:context_status` stream event. The telemetry itself is
+not injected into the model's conversation; what the model gets is one short
+line, as a tail system message (`kind: context`), when usage rises into a bucket
+whose guidance asks it to change how it works (from the second threshold, 40%
+by default, up; never on a fall or a cadence tick, and not again for a bucket a
+resumed session's line already names):
+
+`[CONTEXT: about 55% of the context window is in use (estimated; bucket=40plus). context moderate — prefer targeted and range reads over full-file dumps]`
+
+The native loop only (the chat loop has no context status). The event carries
+a `status` string using this prefix:
+
+`CONTEXT_STATUS ...`
+
+Emission behavior:
+
+- A status is emitted when estimated usage crosses configured threshold buckets.
+- Optional cadence-based updates can also be enabled every N rounds.
+- This is warn-only behavior (no automatic history truncation).
+- When the model server reports real `usage` fields in the stream payload, the
+  telemetry uses those actual token counts (prefixed `src=server`) instead of the
+  synthetic char-based estimate (`src=estimate`). The guidance text is dynamic
+  and escalates with the bucket: healthy → proceed normally; moderate → prefer
+  targeted/range reads; elevated → be concise, avoid large re-reads; critical →
+  summarize aggressively and delegate broad work to subagents.
+
+Configuration:
+
+- `SAMAGOTCHI_CONTEXT_STATUS` (`true` by default): set to `false` or `0` to disable telemetry.
+- `SAMAGOTCHI_CONTEXT_WINDOW_TOKENS` / `context.window_tokens`: context window size for when the server doesn't report one. chi asks llama.cpp for its real window first (`/props`, the per-slot `n_ctx`); this setting only fills in when it can't (mlx, oMLX, server down), and 256000 is the last resort.
+- `SAMAGOTCHI_CONTEXT_CHARS_PER_TOKEN` (default `4.0`): heuristic ratio for char-to-token estimation.
+- `SAMAGOTCHI_CONTEXT_STATUS_THRESHOLDS` (default `20,40,60,80`): comma-separated threshold percentages.
+- `SAMAGOTCHI_CONTEXT_STATUS_CADENCE` (default `0`): emit every N rounds in addition to threshold crossings.

data/docs/internals/gemma4-contract.md

@@ -0,0 +1,23 @@
+# Gemma 4 behavior contract
+
+This project uses canonical Gemma 4 tool-call parsing and explicit thought-context handling.
+
+## Canonical Tool Calls Only
+
+The kernel loop accepts canonical calls in this format:
+
+`<|tool_call>call:NAME{...}<tool_call|>`
+
+XML tool tags and declaration-echo parsing are intentionally not supported.
+
+## Thought Context Rules
+
+Thought handling follows the Gemma guidance:
+
+- Include `<|think|>` in the system instruction to activate thinking mode.
+- When thinking mode is active, the model may emit internal reasoning as `<|channel>thought ... <channel|>`.
+- Standard multi-turn: prior model thoughts are stripped from conversation history before the next turn.
+- Function/tool-calling exception: during a single turn that includes tool calls, thoughts are not stripped between those tool-call rounds.
+- Final model output returned to the caller is thought-stripped.
+
+In short, raw thought blocks are treated as in-turn transient context, not durable history.

data/docs/internals/tool-guardrails.md

@@ -0,0 +1,45 @@
+# Tool output guardrails
+
+## Read Tool Size Guardrails
+
+The `read` tool now applies adaptive limits to avoid accidental context exhaustion
+when opening very large files (for example, VCR cassettes).
+
+Behavior:
+
+- Small files: return full file content.
+- Large files: return a head+tail preview plus truncation metadata.
+- Extremely large files: return an error indicating the hard size limit.
+
+Configuration:
+
+- `SAMAGOTCHI_READ_TRUNCATE_AT_BYTES` (default `65536`): files above this size return a preview instead of full content.
+- `SAMAGOTCHI_READ_PREVIEW_BYTES` (default `12288`): total preview budget split across head and tail.
+- `SAMAGOTCHI_READ_HARD_MAX_BYTES` (default `2097152`): files above this size return `Error: file too large`.
+
+Optional preview telemetry:
+
+- `SAMAGOTCHI_READ_TELEMETRY_THRESHOLD_PCT` (default `80`): include estimated preview token impact only when preview payload is at or above this percentage of the configured context window.
+
+Telemetry uses existing context estimation settings:
+
+- `SAMAGOTCHI_CONTEXT_WINDOW_TOKENS`
+- `SAMAGOTCHI_CONTEXT_CHARS_PER_TOKEN`
+
+## Execute Tool Output Guardrails
+
+The `execute` tool applies the same guardrail model to command output:
+
+- Small stdout/stderr: returned in full.
+- Large stdout/stderr: returned as head+tail previews with truncation metadata.
+
+Configuration:
+
+- `SAMAGOTCHI_EXECUTE_TRUNCATE_AT_BYTES` (default `65536`): output above this size is truncated.
+- `SAMAGOTCHI_EXECUTE_PREVIEW_BYTES` (default `12288`): total preview budget split across head and tail.
+- `SAMAGOTCHI_EXECUTE_TELEMETRY_THRESHOLD_PCT` (default `80`): include estimated output token impact only when threshold is crossed.
+
+Implementation note:
+
+- Shared logic lives in `lib/samagotchi/tools/output_guardrails.rb` and is used by both `read` and `execute`.
+- Additional tools that can emit large payloads should rely on this shared helper for consistent behavior.