samagotchi 0.99.0 → 0.100.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '0185e889922200db9f6882d899b3ff17c74d296aa8c7823a7040e45e308edc47'
-  data.tar.gz: addddd537eac6fc703d0e217c7a968446ca44bb53f8ee501e61de86b1163085c
+  metadata.gz: 10cafc8e1deb147528195213bd69b946f428918a8c344c57022b2c905cd2f4fb
+  data.tar.gz: 6b6764b06a4effc61ac2edd1d2221d7afd232b2a8ce3470f0b14280d3ded432d
 SHA512:
-  metadata.gz: 62a2aaff51d6bbc45cfcc59e3d199444448cd838c229fbe4bda717658b6ba83fc7f273326ea0d8e8cb3e34839bd3c78ba472a5792589dbfe87a5dd1a8df2c5a7
-  data.tar.gz: 8b68d54a05c89461dba2428496111897cf85ca1cc70ac70f2b1621edcce7d70908243e181644b7086557d347fc80c51305a7b3df446c9299a09c2ec8e1cd113b
+  metadata.gz: a4da078e7bb452a96fbc8d38f9565946fa12a3e3b8185e35f26032fcc2a3ae76249ec5ad7712dd12b74fec0f52db5fac7c03890f5074fca747985944b50f8e26
+  data.tar.gz: 3cc980b577869624c31a8c577b69612198569875d5c3b1e2f9070a4aebed2b5d4e6d4d29d44e25e56e2144b2346f4017352dca2e7a01b2898bc6fa5046b4459e

data/CHANGELOG.md

@@ -8,6 +8,24 @@ and commands may change between minor versions. How releases are made:
 
 ## [Unreleased]
 
+## [0.100.0] - 2026-10-22
+
+### Added
+
+- Plugins can read the session's work so far with `ctx.usage`: turns, tool calls (by tool), steps and active time
+  (generations plus tool calls, never a wait on a question), across workers, the same numbers `/stats` shows. The
+  bundle test kit sets it with `bundle.set(usage: {...})`. See [docs/plugins.md](docs/plugins.md).
+- The `work-cap` bundle (in the `core` profile; `chi update` installs it): an optional per-session cap on tool calls
+  and active minutes across turns, the bound a session whose step-limit Continue keeps being answered otherwise
+  lacks. At a cap the turn pauses on Continue / Stop, the question naming the session's totals; `/workcap` shows or
+  sets it, `chi send --new --set work-cap.tool_calls=400` caps a child. Inert until a cap is set. See
+  [docs/plugins.md](docs/plugins.md#the-work-cap-bundle).
+
+### Fixed
+
+- An empty `hooks:` key in config.yml no longer crashes chi, and a malformed `hooks:` section (or one event's
+  entry) warns instead of being dropped without a word.
+
 ## [0.99.0] - 2026-10-22
 
 ### Added
@@ -3774,7 +3792,8 @@ and long-lived sessions.
 - A macOS desktop helper (`chi desktop install`): a "Send to chi" Service and a
   hotkey panel that send selected text or the clipboard to your sessions.
 
-[Unreleased]: https://github.com/dm1try/samagotchi/compare/v0.99.0...HEAD
+[Unreleased]: https://github.com/dm1try/samagotchi/compare/v0.100.0...HEAD
+[0.100.0]: https://github.com/dm1try/samagotchi/compare/v0.99.0...v0.100.0
 [0.99.0]: https://github.com/dm1try/samagotchi/compare/v0.98.0...v0.99.0
 [0.98.0]: https://github.com/dm1try/samagotchi/compare/v0.97.0...v0.98.0
 [0.97.0]: https://github.com/dm1try/samagotchi/compare/v0.96.0...v0.97.0

data/README.md

@@ -78,8 +78,8 @@ Messages API, picks the
 model (or asks, when there are several), sends one test request and writes
 the config. With a config already there, it adds a `hosts:` entry and keeps
 the rest of the file. Then it installs the `core` bundles (loop-guard,
-check-in, guardrails, slow-commands, agents-md, cost-cap: the safety set for a
-small local model, the cost cap inert until you set one) and, on a terminal, offers `dev` (known-names, mcp, btw, skills,
+check-in, guardrails, slow-commands, agents-md, cost-cap, work-cap: the safety set for a
+small local model, the cost and work caps inert until you set one) and, on a terminal, offers `dev` (known-names, mcp, btw, skills,
 source-links, github-pr, coordinator, claude-peer, codex-peer, ruby, model-notes; see
 [Bundle profiles](docs/memory.md#bundle-profiles-core-and-dev)). Edit the
 file later as in [Configure](#configure); `chi bootstrap --help` has the

data/docs/architecture.md

@@ -411,7 +411,10 @@ stay the turns' only. `SessionMetrics#persist` is serialized (its own mutex, tak
 threads' saves land in snapshot order.
 A bundle's `ctx.cost` reads the same sums (`SessionMetrics#cost`, a frozen `SessionMetrics::Cost`): the `tokens`
 block's `cost_sum` and `cost_estimate_sum` with the running turn's finished generations folded in, plus the `side`
-block's, so it counts what earlier workers spent too ([plugins.md](plugins.md)).
+block's, so it counts what earlier workers spent too ([plugins.md](plugins.md)). Its `ctx.usage` reads the work
+(`SessionMetrics#usage`, a frozen `SessionMetrics::Usage`): the snapshot's `turns`, `tool_calls_total` /
+`tool_calls_by_tool` and `iterations_total`, and `active_ms`, the generations' `gen_ms` plus the finished tool
+records' `duration_ms` (tallied per tool as they are counted; `ask_user_question`'s, a wait on the user, left out).
 
 The page's frequent reads of `GET /api/sessions/:id` stay light too:
 - `?tail=1&recent=1` (each turn's end, a cancel, an answer display): `{tail, session: {id, status,
@@ -609,7 +612,7 @@ A map of the parts the overview above doesn't name (paths under `lib/samagotchi/
 | Attached context | `context_sources.rb` (`ContextSources`), `context_poller.rb`, `context_absorber.rb`, `peer_sources.rb` (`PeerSources`: the sources peer bundles declare) | External sources a session keeps fresh, and the peer loop's wakes ([context.md](context.md)). |
 | LLM context strategies | `llm_context_strategy.rb`, `llm_context_view.rb`, `llm_context_stale.rb`, `llm_context_forget.rb` | What a request sends of the history (none, stale, forget) ([internals/llm-context-forget.md](internals/llm-context-forget.md)). |
 | Session chains | `session_continue.rb` (`SessionContinue`), `session_chain.rb` (`SessionChain`) | A session that continues an earlier one. `SessionChain.opener_for` gives the text web `continue →` prefills in the new link: the previous link's own first typed message when that link continues one itself, else nil (the 201's `opener`; not saved) ([sessions.md](sessions.md)). |
-| Analytics | `analytics_file.rb` (`AnalyticsFile`), `session_metrics/totals.rb` (`SessionMetrics::Totals`), `session_metrics/model_segment.rb` (`SessionMetrics::ModelSegment`) | A session's `analytics.json` (`SessionMetrics#persist`); the sums over its turn records (`Totals`: tokens, cost, speeds, kept as running counters) and their split per model after a `/model` switch (`ModelSegment`: a run of turns on one model, the `model_segments` rows); `session_metrics/cost.rb` (`SessionMetrics::Cost`): the spend `ctx.cost` reads. `session_metrics/side_totals.rb` (`SessionMetrics::SideTotals`) and `side_usage.rb` (`SideUsage`): the side requests' sums, apart from the turns'. |
+| Analytics | `analytics_file.rb` (`AnalyticsFile`), `session_metrics/totals.rb` (`SessionMetrics::Totals`), `session_metrics/model_segment.rb` (`SessionMetrics::ModelSegment`) | A session's `analytics.json` (`SessionMetrics#persist`); the sums over its turn records (`Totals`: tokens, cost, speeds, kept as running counters) and their split per model after a `/model` switch (`ModelSegment`: a run of turns on one model, the `model_segments` rows); `session_metrics/cost.rb` (`SessionMetrics::Cost`): the spend `ctx.cost` reads; `session_metrics/usage.rb` (`SessionMetrics::Usage`): the work `ctx.usage` reads. `session_metrics/side_totals.rb` (`SessionMetrics::SideTotals`) and `side_usage.rb` (`SideUsage`): the side requests' sums, apart from the turns'. |
 | Images / vision | `image_store.rb` (`ImageStore`), `vision_support.rb`, `vision_context.rb` | Stored prompt images and whether a model takes them. |
 | Toolkits | `toolkit.rb` (`Toolkit`), `toolkit_binding.rb` (`ToolkitBinding`, the Engine's seam), `toolkit_command.rb` (`/toolkit`), `tools/registry.rb` (`Registry#toolkit`, `#left_out_names`), `web/public/toolkit_chip.js` | Which registered tools a session's prompts declare: saved in the session, resolved at a turn's start (`Engine#apply_toolkit!`), named in the prompt's not-loaded line, a kit's prompt text after the appended files; `chi.toolkit` and `ctx.use_toolkit` for plugins ([configuration.md](configuration.md#toolkits)). |
 | Tool index | `tools/tool_index.rb` (`Tools::ToolIndex`), `tools/deferred_tools.rb` | `find_tools` and `call_tool`: the tools a session knows but doesn't declare one by one (an mcp bundle's servers through `chi.tool_source`, the built-ins its toolkit leaves out), searched and called by name ([plugins.md](plugins.md)). On `api: anthropic` they also go out deferred, a hit loads its matches and the model calls them by name ([internals/anthropic.md](internals/anthropic.md)). |

data/docs/bundle-authoring.md

@@ -129,7 +129,7 @@ class, a hand-built `ctx`), that is a gap in the kit: say so to the user rather
   of a checksum mismatch, and a line with no sha installs unchecked. `chi bundle check --fix` rewrites them; run it
   after the last edit.
 - **requires_chi.** Use the chi the user runs (`chi --version`). `check` warns when the plugin calls something
-  newer than the floor (`ctx.http` needs 0.80.0, `ctx.cost` 0.83.0, `ctx.sessions.children` 0.34.0). A keyword added
+  newer than the floor (`ctx.http` needs 0.80.0, `ctx.cost` 0.83.0, `ctx.usage` 0.100.0, `ctx.sessions.children` 0.34.0). A keyword added
   later it can't see: `ctx.ask_model(model:)` needs 0.80.0, `ctx.sessions.send(delivery:)` 0.64.0.
 - **trust_level.** Leave it out. `reviewed` / `trusted` are for someone who reviewed the bundle, not its author.
 - **Restart.** A session loads bundles when it starts: after an install or a settings change, the user starts a

data/docs/cli.md

@@ -84,7 +84,7 @@ chi bootstrap                            # try localhost 8080, 11434, 1234, 8000
   or with anchors gets the lines printed to paste instead. `--dry-run` shows
   what it would write.
 - **The bundles.** Unless writing the config failed, it installs the system
-  bundle and the `core` profile (loop-guard, check-in, guardrails, slow-commands, agents-md, cost-cap), one line
+  bundle and the `core` profile (loop-guard, check-in, guardrails, slow-commands, agents-md, cost-cap, work-cap), one line
   each; on a terminal it then asks `Also install dev (known-names, mcp, btw,
   skills, source-links, github-pr, coordinator, claude-peer, codex-peer, ruby, model-notes)? [y/N]`. Run again, it installs nothing new: a bundle
   you uninstalled stays out ([Bundle profiles](memory.md#bundle-profiles-core-and-dev)).

data/docs/guardrails.md

@@ -125,7 +125,7 @@ answers it. Every question's options carry an **effect**, set by whoever asks:
 - `deny`: Deny on an approval, Stop on the step-limit question or a plugin's
   stop option;
 - `spend`: more time and tokens, no new permission (Continue on the step-limit
-  question, cost-cap's Continue);
+  question, cost-cap's and work-cap's Continue);
 - `permit`: one tool call (an approval's "Allow once");
 - `permit_wide`: more than one call (this session, this repo or directory,
   the rule).
@@ -140,7 +140,7 @@ guardrails:
 - `hard`: `deny` and `answer` only. A parent can deny an approval
   (`--option Deny --text "why"`, `--text` alone or `--dismiss`), Stop a
   step-limit question and answer plain questions.
-- `standard`: also `spend`: a parent may Continue a turn (or cost-cap's cap).
+- `standard`: also `spend`: a parent may Continue a turn (or cost-cap's or work-cap's cap).
 - `soft` (the default): also `permit`: `chi answer --option "Allow once"`
   goes through, picked by the option's scope, not its label.
 

data/docs/hooks.md

@@ -26,6 +26,9 @@ hooks:
       on_error: skip
 ```
 
+Each event key holds a list of entries. A `hooks:` that isn't a mapping, or an event key that isn't a list
+(`before_turn: guard.rb`), warns at each start and loads nothing for it; an empty key loads nothing, silently.
+
 ## Plugin Format
 
 Each plugin is a `.rb` file in the hooks directory. The class name must match
@@ -672,7 +675,7 @@ Notes:
 - 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). There `ctx.notify`, `ctx.steer` and the other `ctx` helpers act as this page's `event[:notify]`… do for the event the block runs for.
-- Shipped bundles (each in a profile: `core` or `dev`, see [Bundle profiles](memory.md#bundle-profiles-core-and-dev)): `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 source-links` (a hook: announces source refs, see [The source-links bundle](#the-source-links-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)) `chi bundle install loop-guard` (a plugin: breaks tool-call loops, see [Plugins](plugins.md#the-loop-guard-bundle)), `chi bundle install check-in` (a plugin: checks on a long turn, see [Plugins](plugins.md#the-check-in-bundle)), `chi bundle install slow-commands` (a plugin: commands that ran past the execute limit are run as tasks next time, see [Plugins](plugins.md#the-slow-commands-bundle)), `chi bundle install agents-md` (a plugin: a nested AGENTS.md is steered into the conversation on the first touch under its directory, see [Plugins](plugins.md#the-agents-md-bundle)), `chi bundle install cost-cap` (a plugin: a per-session $ cap, `/cap`, see [Plugins](plugins.md#the-cost-cap-bundle)), `chi bundle install ruby` (a plugin: an RSpec run with no examples at all, a hint, see [Plugins](plugins.md#the-ruby-bundle)) `chi bundle install skills` (a plugin: `/skill`, versions of skills, see [Plugins](plugins.md#the-skills-bundle)), `chi bundle install github-pr` (attached context: the branch's open PR, see [Plugins](plugins.md#the-github-pr-bundle)), `chi bundle install coordinator` (a plugin: parallel work in worktrees and child sessions, see [Plugins](plugins.md#the-coordinator-bundle)), `chi bundle install claude-peer` / `codex-peer` (a plugin: talk to a Claude Code or Codex session, see [Plugins](plugins.md#the-claude-peer-bundle)) and `chi bundle install model-notes` (memories: reviewed model notes, see [Plugins](plugins.md#the-model-notes-bundle)).
+- Shipped bundles (each in a profile: `core` or `dev`, see [Bundle profiles](memory.md#bundle-profiles-core-and-dev)): `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 source-links` (a hook: announces source refs, see [The source-links bundle](#the-source-links-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)) `chi bundle install loop-guard` (a plugin: breaks tool-call loops, see [Plugins](plugins.md#the-loop-guard-bundle)), `chi bundle install check-in` (a plugin: checks on a long turn, see [Plugins](plugins.md#the-check-in-bundle)), `chi bundle install slow-commands` (a plugin: commands that ran past the execute limit are run as tasks next time, see [Plugins](plugins.md#the-slow-commands-bundle)), `chi bundle install agents-md` (a plugin: a nested AGENTS.md is steered into the conversation on the first touch under its directory, see [Plugins](plugins.md#the-agents-md-bundle)), `chi bundle install cost-cap` (a plugin: a per-session $ cap, `/cap`, see [Plugins](plugins.md#the-cost-cap-bundle)), `chi bundle install work-cap` (a plugin: a per-session cap on tool calls and active minutes, `/workcap`, see [Plugins](plugins.md#the-work-cap-bundle)), `chi bundle install ruby` (a plugin: an RSpec run with no examples at all, a hint, see [Plugins](plugins.md#the-ruby-bundle)) `chi bundle install skills` (a plugin: `/skill`, versions of skills, see [Plugins](plugins.md#the-skills-bundle)), `chi bundle install github-pr` (attached context: the branch's open PR, see [Plugins](plugins.md#the-github-pr-bundle)), `chi bundle install coordinator` (a plugin: parallel work in worktrees and child sessions, see [Plugins](plugins.md#the-coordinator-bundle)), `chi bundle install claude-peer` / `codex-peer` (a plugin: talk to a Claude Code or Codex session, see [Plugins](plugins.md#the-claude-peer-bundle)) and `chi bundle install model-notes` (memories: reviewed model notes, see [Plugins](plugins.md#the-model-notes-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:

data/docs/memory.md

@@ -387,7 +387,7 @@ profiles, meta bundles that install a set of them:
 
 | profile | bundles |
 |---|---|
-| `core` | loop-guard, check-in, guardrails, slow-commands, agents-md, cost-cap: the recommended safety set |
+| `core` | loop-guard, check-in, guardrails, slow-commands, agents-md, cost-cap, work-cap: the recommended safety set |
 | `dev` | known-names, mcp, btw, skills, source-links, github-pr, coordinator, claude-peer, codex-peer, ruby, model-notes |
 
 `chi bootstrap` installs `core` and, on a terminal, offers `dev`. An existing

data/docs/plugins.md

@@ -751,6 +751,7 @@ full label, `plugin.rb (bundle my-bundle)`.
 | `ctx.model` | the model the session runs on now: its resolved ref (`host:id`), right after `/model` too |
 | `ctx.model_key` | that model's memory overlay key (`<name>.<key>.md`, what `memory_write current_model_only` writes) |
 | `ctx.cost` | the session's spend so far, read now, as a frozen value: `total` (USD, reported + estimated, side requests included; 0.0 before any), `reported` (by providers, `usage.cost`), `estimated` (from `hosts.<name>.models` prices; a generation is one or the other, never both), `side` (recap, `/btw`, `ask_model`: their share of `total`) and `known?` (false while generations or side requests ran but none was reported or priced, so a limit on it can't be enforced; a session with some priced generations reads known, the unpriced ones counting 0). It includes the running turn's finished generations and what earlier workers of the session spent. Use its methods, not its class. Needs chi 0.83.0 |
+| `ctx.usage` | the session's work so far, read now, as a frozen value: `turns` (finished ones and the running one), `tool_calls` and `tool_calls_by_tool` (every call, running ones included; canonical names: an alias counts under its tool, a `call_tool` call under the inner tool), `steps` (the loop rounds that dispatched tools, `/stats`' iterations) and `active_ms` (`active_minutes` too): work time, the generations' time plus the finished tool calls' time, never the waits between them (a question, an approval, the user's answer to `ask_user_question`), with `tool_ms_by_tool` its tool part by tool, so a waiting tool's time (`task_wait`) can be left out. Its counts are the ones `/stats` and `chi sessions stats` show, earlier workers' included. Use its methods, not its class. Needs chi 0.100.0 (guard it with `ctx.respond_to?(:usage)`) |
 | `ctx.settings` | the bundle's settings, frozen: config.yml's `bundles: <bundle>:` with the session's own `--set` values laid over it ([Per-session settings](#per-session-settings)); the config alone until the session is bound (in `register` and `chi.ctx`) |
 | `ctx.data_dir` | `$XDG_STATE_HOME/samagotchi/plugins/<bundle>/`, created on first use. A session's own state goes in `sessions/<id>.json` or `sessions/<id>/` there: chi removes it when the session is deleted, discarded or pruned |
 | `ctx.log` | `ctx.log.info(:event, key: value)`: debug-log records tagged `plugins`, with `bundle=<bundle>` |
@@ -1120,7 +1121,7 @@ CHANGELOG line and bumps the shipped bundles that use it. Anything else under
 
 **Stable**
 
-1. `Samagotchi::Plugin::Api` / `chi.*` and `ctx` as documented above (`ctx.cost`'s value by its methods), including
+1. `Samagotchi::Plugin::Api` / `chi.*` and `ctx` as documented above (`ctx.cost`'s and `ctx.usage`'s values by their methods), including
    `Samagotchi::Plugin::ToolResult`, `Samagotchi::Plugin::ModelError` (and its
    subclass `Samagotchi::Plugin::ModelCancelled`),
    `Samagotchi::Plugin::Service::Stopped`, `Samagotchi::Plugin::Sessions::Error`
@@ -1187,6 +1188,7 @@ bundle.sessions.on(:children) { |all:| [] }              # ctx.sessions, scripte
 bundle.http.stub(:post, "http://127.0.0.1:9000/classify", json: { label: "safe" })   # ctx.http, never the network
 bundle.set(running: false)                               # the session's values: cwd:, messages:, cancelled: …
 bundle.set(cost: 2.5)                                    # ctx.cost: reported USD, or { reported:, estimated:, side:, known: }
+bundle.set(usage: { tool_calls: 40, active_ms: 600_000 }) # ctx.usage: { turns:, tool_calls:, tool_calls_by_tool:, steps:, active_ms:, tool_ms_by_tool: }
 bundle.set(session_settings: { "cap" => 1 })             # the session's --set values (Bundle.load takes session_settings: too)
 bundle.tool_loads.last.names                             # ctx.load_tools calls; set(load_tools_staged: [...]) limits what they stage
 bundle.shutdown
@@ -1222,6 +1224,10 @@ bundle.shutdown
 - **`ctx.cost`** is zero and known unless the test sets it: `bundle.set(cost: 2.5)` (reported USD), a Hash of the
   parts (`reported:`, `estimated:`, `side:`, `known:`; `total` is reported + estimated) or a callable giving either,
   called at each read (a counting lambda shows whether the bundle read it).
+- **`ctx.usage`** is zero unless the test sets it: `bundle.set(usage: {...})`, a Hash of the parts (`turns:`,
+  `tool_calls:`, `tool_calls_by_tool:`, `steps:`, `active_ms:`, `tool_ms_by_tool:`; zeros for the rest, an unknown
+  part raises; `tool_calls` defaults to the sum of `tool_calls_by_tool`, `active_ms` to the sum of
+  `tool_ms_by_tool`) or a callable giving one, called at each read.
 - **`session_settings:`** (on `Bundle.load` and `bundle.set`) are the session's own `--set` values for the bundle,
   keys its manifest lists in `session_settings:` (another key, or a value of another type than the manifest gives
   it, raises `ArgumentError`, as chi refuses it). `ctx.settings`
@@ -1680,6 +1686,64 @@ its own card and doesn't wake its parent ([sessions.md](sessions.md#delegating))
 The state is one file per session, `<data_dir>/sessions/<session id>.json` (`{"cap": 3.0, "step": 3.0}`), removed
 with the session.
 
+Its sibling for work instead of money, tool calls and active minutes across the session's turns, is
+[the work-cap bundle](#the-work-cap-bundle): the cap a local model (no cost) can have.
+
+## The work-cap bundle
+
+`chi bundle install work-cap` installs the bundle shipped with chi (`chi bootstrap` installs it with the `core`
+profile; an existing install gets it with `chi update`). It caps the work one session does across its turns: tool
+calls and active minutes. The per-turn meters reset every turn (the step limit, check-in, loop-guard), and a
+Continue on the step-limit question starts the next 300 steps; a parent agent may answer that Continue itself
+(`chi answer`), so a child it keeps continuing has no overall bound but cost-cap's `$`, and on a local model none.
+work-cap is that bound, with cost-cap's shape: the harness watches, the model never sees any of it. It is inert
+without a cap, and there is none by default.
+
+```yaml
+# config.yml
+bundles:
+  work-cap:
+    child: {tool_calls: 500, minutes: 90}   # delegate children with no own value
+    default: {}         # every other session (and a delegate without child:); empty: no cap
+    warn_at: 0.8        # tell the user (only) once at this share of a cap; 0/off: no warning
+    ignore_tools: [task_wait, task_get, delegate, delegate_result]   # not counted: waiting
+```
+
+- **What counts** (`ctx.usage`): **tool calls**, the session's own across its turns and workers, less
+  `ignore_tools` (the waiting tools by default, `delegate` among them since it blocks on its child, so a session
+  waiting on a long task or a child isn't capped for waiting); and **active minutes**, work time: the generations' time plus the finished tool calls' time (less
+  `ignore_tools`' time), never a wait (a question, its own included, an approval, the user's answer to
+  `ask_user_question`), so idle time and a Continue answered hours later don't count.
+- **When it checks:** before each generation, like cost-cap: the overshoot is at most one generation's tool calls.
+  When the step limit and a work cap fall in the same turn, the work cap asks first, and its Stop ends the turn.
+- **At `warn_at` of a cap** you get one notice per meter, `work-cap> 320 of 400 tool calls (80%)`; a raised cap
+  warns again.
+- **At a cap** the turn pauses on a question (header "Work cap") that names the session's totals, so a parent
+  answering it decides on the whole picture: `Work cap reached: 412 tool calls of 400 (6 turns, 47 min active,
+  $1.20). Continue raises it to 800.` **Continue** raises the cap by another cap's worth (as many steps as it
+  takes to pass the work, saved for the session), **Stop** stops the turn (`canceled` with `stopped_by: work-cap`)
+  with a card showing the totals. Both meters at once: one question naming both, Continue raises each. With no one
+  to ask (`--non-interactive`) it stops. Continue is tagged `:spend`, as cost-cap's: a parent agent may Continue
+  under `guardrails.parent_answers: soft` or `standard`, only Stop under `hard` (see
+  [Guardrails](guardrails.md#answers-from-a-parent-agent)).
+- **The caps of a session**, each meter on its own: the one `/workcap` or a Continue set, else its own value (`chi
+  --set work-cap.tool_calls=400`, `work-cap.minutes=60`, `chi send --new --set …`; `off`, `0` or a negative number
+  for none), else `child:`'s for a delegate child, else `default:`'s. Minutes in config.yml read `90`, `90m` or
+  `1.5h`. A value that doesn't read (`tool_calls: many`, a `default:` that isn't a mapping) gets one notice,
+  `work-cap: tool_calls: "many" isn't a number or off; using default.tool_calls: (400)`, and the next value is used,
+  never a silent no cap.
+
+**`/workcap`** (works while a turn runs; the next generation reads it):
+
+- `/workcap`: `work-cap: 320 of 400 tool calls (6 turns, 47 min active, $1.20)`, or `work-cap: no cap (…)` with the
+  totals.
+- `/workcap 400`: the tool-call cap (and what Continue adds) becomes 400 for this session; `/workcap 90m` or
+  `/workcap 2h`: the active-minutes cap.
+- `/workcap off` (or `/workcap 0`): no work cap for this session, over the config.
+
+The state is one file per session, `<data_dir>/sessions/<session id>.json` (`{"tool_calls": {"cap": 800, "step":
+400}}`, a meter's `"cap": null` for off).
+
 ## The check-in bundle
 
 `chi bundle install check-in` installs the bundle shipped with chi (`chi
@@ -1712,7 +1776,8 @@ what it has found. check-in counts the turn's tool calls, and when there are
 - **`mode: notify`**: a notice line only.
 
 The count is per turn: a new turn (a prompt, a continue, a reminder) starts
-from zero; steering merged into the running turn doesn't reset it. The polling
+from zero; steering merged into the running turn doesn't reset it (a cap
+across the session's turns is [the work-cap bundle](#the-work-cap-bundle)). The polling
 tools are not counted. A nudge that arrives after the model's final answer is
 dropped (logged), never restarting a turn that is done; the card's "Nudged the
 model at N tool calls" then becomes "The answer came first; nudge not sent."

data/docs/releasing.md

@@ -13,7 +13,7 @@ can run the whole release; the user approves the notes before the tag and the
   and `rake release:check` enforce it). The system bundle upgrades itself when
   chi starts.
 - **Every other shipped bundle** (btw, check-in, guardrails, known-names,
-  loop-guard, mcp, skills, slow-commands, agents-md, cost-cap, source-links, github-pr, coordinator, claude-peer, codex-peer, ruby, model-notes, and the profiles core and dev) has its own semver in its
+  loop-guard, mcp, skills, slow-commands, agents-md, cost-cap, work-cap, source-links, github-pr, coordinator, claude-peer, codex-peer, ruby, model-notes, and the profiles core and dev) has its own semver in its
   `manifest.yml` and, when it needs a newer chi, a `requires_chi:` line. They never upgrade by themselves: users run
   `chi update` (all of them, with the gem) or `chi bundle upgrade NAME`. So:
   - a change to a bundle's files bumps that bundle's `version:`

data/docs/sub-agent.md

@@ -47,7 +47,9 @@ chi answer ID --question QID --dismiss [--timeout S] [--format json]
 
 A child with a bundle setting of its own, such as a $ cap (the [cost-cap bundle](plugins.md#the-cost-cap-bundle)):
 `chi send --new --wait --format json --set cost-cap.cap=3 -m "task"`. At the cap the wait exits 3 with the cost-cap
-question; `chi answer ID --question QID --option Continue` (or `Stop`) answers it.
+question; `chi answer ID --question QID --option Continue` (or `Stop`) answers it. A cap on the child's work across
+its turns (the [work-cap bundle](plugins.md#the-work-cap-bundle)), the bound a parent that keeps answering the step
+limit's Continue doesn't otherwise have: `--set work-cap.tool_calls=400` (or `work-cap.minutes=60`, active minutes).
 
 `chi answer` waits after answering, the same way `chi send --wait` does, so the
 next question comes back as exit 3 again. What it waits for is the answered
@@ -122,7 +124,10 @@ relayed to the parent's user the way approvals are.
 
 A session at its cost cap (the [cost-cap bundle](plugins.md#the-cost-cap-bundle)) waits the same way, as a
 question of kind `hook` with header "Cost cap" and options `Continue` and `Stop`: `--option Continue` raises the cap
-by another cap's worth and the turn goes on, `--option Stop` ends it `canceled` with `stopped_by: cost-cap`.
+by another cap's worth and the turn goes on, `--option Stop` ends it `canceled` with `stopped_by: cost-cap`. A session at its work cap (the
+[work-cap bundle](plugins.md#the-work-cap-bundle)) asks the same, header "Work cap", the question naming the
+session's totals (`Work cap reached: 412 tool calls of 400 (6 turns, 47 min active, $1.20). Continue raises it to
+800.`); `stopped_by: work-cap` on Stop.
 
 ## Approvals
 

data/lib/samagotchi/bundles/core/manifest.yml

@@ -1,11 +1,11 @@
 ---
 name: core
-version: 0.3.4
+version: 0.4.0
 scope: system
 description: "Recommended safety set"
 trust_level: reviewed
-# Its members' highest floor (cost-cap's)
-requires_chi: ">= 0.92.0"
+# Its members' highest floor (work-cap's: ctx.usage, raised at the release)
+requires_chi: ">= 0.100.0"
 includes:
 - loop-guard
 - check-in
@@ -13,3 +13,4 @@ includes:
 - slow-commands
 - agents-md
 - cost-cap
+- work-cap

data/lib/samagotchi/bundles/system/manifest.yml

@@ -1,6 +1,6 @@
 ---
 name: samagotchi-system
-version: 0.99.0
+version: 0.100.0
 scope: system
 description: Default system memories — identity, self map, config modification protocol, memory guide and the delegated-session rules
 files:

data/lib/samagotchi/bundles/work-cap/manifest.yml

@@ -0,0 +1,13 @@
+---
+name: work-cap
+version: 0.1.0
+scope: system
+description: "A per-session work cap (tool calls, active minutes) across turns: at a cap the turn pauses on Continue (another cap's worth) / Stop with the session's totals, a warning at 80% goes to the user only; /workcap shows or sets it"
+trust_level: reviewed
+plugin:
+  file: plugin.rb
+  sha256: sha256:d4de4b835d1657223517f3d6a5d8a9b089b7c8fad08ed077f72748369323bd65
+# ask_user's effects: are in chi 0.92.0; ctx.usage is new in the next chi
+requires_chi: ">= 0.100.0"
+# chi --set work-cap.tool_calls=400 / work-cap.minutes=60: the session's own caps, a number or off
+session_settings: {tool_calls: number, minutes: number}

data/lib/samagotchi/bundles/work-cap/plugin.rb

@@ -0,0 +1,391 @@
+# frozen_string_literal: true
+
+# The work-cap bundle (docs/plugins.md, The work-cap bundle): a per-session
+# cap on the work a session does across its turns (ctx.usage: tool calls,
+# active minutes), the session-wide bound the per-turn step limit and
+# check-in don't give. Before each generation it compares the work with the
+# caps: at warn_at of a cap the user (only) gets one notice, at a cap the
+# turn pauses on a question, Continue (the cap goes up by a step) or Stop
+# (the turn stops, with a card). With no one to ask it stops. The question
+# names the session's totals, so a parent agent answering it decides on the
+# whole picture. The model never sees any of it: no tool, no steer, no
+# prompt text. cost-cap (the $ cap) is its sibling; the wordings follow it.
+#
+# Settings (config.yml, bundles: work-cap:), from ctx.settings, never at
+# load: the caps are resolved once per session (see State below), so a
+# config change reaches a running session through /workcap or a new
+# session; warn_at and ignore_tools are read at each check.
+#   tool_calls: 400   this session's own tool-call cap (session_settings:,
+#                     chi --set work-cap.tool_calls=400); 0/off: none
+#   minutes: 60       this session's own cap on active minutes, same rules
+#   child: {tool_calls: 500, minutes: 90}   delegates (ctx.delegate?) with
+#                     no own value
+#   default: {}       every other session (and a delegate without child:)
+#   warn_at: 0.8      the share of a cap that warns; 0/off: no warning
+#   ignore_tools: [task_wait, task_get, delegate, delegate_result]
+#                     tools whose calls and time aren't counted (waiting:
+#                     delegate blocks on its child by default)
+# Each meter resolves on its own: its own value, else child:'s for a
+# delegate, else default:'s. A value that doesn't read (tool_calls: many)
+# warns the user once and the next one is used, never a silent "no cap".
+#
+# What counts: ctx.usage's tool calls and active time (generations plus
+# finished tool calls, never a question's wait), less ignore_tools'.
+#
+# State: <data_dir>/sessions/<session id>.json, {"tool_calls": {"cap": 800,
+# "step": 400}, "minutes": {"cap": null}}, written by /workcap and by
+# Continue; a meter's "cap": null is off for the session, over the config;
+# a meter missing from the file comes from the settings. Resolved once per
+# session id (ctx.delegate? parses the session file) and kept until
+# /workcap or Continue writes a new one.
+require "json"
+require "fileutils"
+
+class Plugin
+  USAGE = "usage: /workcap [N | Nm | Nh | off] (N tool calls, Nm or Nh active time; /workcap alone shows the totals)"
+  OPTIONS = %w[Continue Stop].freeze
+  # For a parent agent's answer (guardrails.parent_answers): Continue
+  # spends more, Stop denies; under hard a parent may only Stop.
+  EFFECTS = { "Continue" => :spend, "Stop" => :deny }.freeze
+  WARN_AT = 0.8
+  METERS = %w[tool_calls minutes].freeze
+  DEFAULT_IGNORE = %w[task_wait task_get delegate delegate_result].freeze
+  # A cap as text: 3, 2.5, .5, 1e1, -1 (a negative is none).
+  NUMBER = /\A-?(?:\d+(?:\.\d*)?|\.\d+)(?:e[-+]?\d+)?\z/i
+  # Minutes as text: a NUMBER, or one with m/min (minutes) or h (hours).
+  DURATION = /\A(?<number>.+?)\s*(?<unit>m|min|mins|minutes|h|hours?)?\z/i
+
+  def initialize(_settings)
+    @mutex = Mutex.new
+    @resolved = nil        # {session:, meters: {meter => {cap:, step:, key:}}, unreadable: {name => value}}
+    @warned = {}           # meter => [session id, cap] the share warning was given for
+    @unread_warned = nil   # the session id the "isn't a number" notice was given for
+  end
+
+  def register(chi)
+    chi.on(:before_generation) { |_event, ctx| check(ctx) }
+    chi.command("/workcap", "see or set this session's work cap: /workcap, /workcap 400, /workcap 90m, /workcap off",
+                anytime: true) do |args, ctx|
+      command(args, ctx)
+    end
+  end
+
+  # A cap (a positive Float) or nil (none, 0, off, false, or a value that
+  # isn't a number: .readable? tells them apart). Minutes take a unit:
+  # 90m, 1.5h.
+  def self.amount(value, meter)
+    number = number(value, meter)
+    number&.positive? ? number : nil
+  end
+
+  # +value+ as a finite Float, else nil. "5." gets its 0 first
+  # (.float_text: Ruby 3.3's Float wants one).
+  def self.number(value, meter)
+    number = case value
+             when Numeric then value.to_f
+             when String then text_number(value.strip, meter)
+             end
+    number if number&.finite?
+  end
+
+  def self.text_number(text, meter)
+    return Float(float_text(text)) if text.match?(NUMBER)
+    return nil unless meter == "minutes" && (match = DURATION.match(text)) && match[:unit]
+    return nil unless match[:number].match?(NUMBER)
+
+    Float(float_text(match[:number])) * (match[:unit].downcase.start_with?("h") ? 60 : 1)
+  end
+
+  # A NUMBER as Float reads it on every Ruby: a bare point ("5.", "5.e1")
+  # gets a 0 after it.
+  def self.float_text(text) = text.sub(/\.(?=e|\z)/i, ".0")
+
+  # Whether +value+ reads as a cap or as none: a number (text too), off,
+  # false or nil; not "many", true or a list.
+  def self.readable?(value, meter)
+    case value
+    when false, nil then true
+    when Numeric then value.finite?
+    when String then value.strip.casecmp?("off") || !number(value, meter).nil?
+    else false
+    end
+  end
+
+  # 400, 2.5: a whole number without its ".0".
+  def self.count(value)
+    rounded = value.round(1)
+    rounded == rounded.to_i ? rounded.to_i.to_s : rounded.to_s
+  end
+
+  private
+
+  def check(ctx)
+    resolved = resolve(ctx)
+    unreadable(ctx, resolved)
+    capped = resolved[:meters].select { |_meter, meter_cap| meter_cap[:cap] }
+    return if capped.empty?
+
+    usage = ctx.usage
+    used = used(ctx, usage)
+    reached = capped.select { |meter, meter_cap| used[meter] >= meter_cap[:cap] }
+    return at_cap(ctx, resolved, reached, usage, used) unless reached.empty?
+
+    share = warn_share(ctx)
+    return unless share
+
+    capped.each do |meter, meter_cap|
+      cap = meter_cap[:cap]
+      next unless used[meter] >= share * cap && first_warning?(meter, [resolved[:session], cap])
+
+      ctx.notify("#{count(used[meter])} of #{count(cap)} #{unit(meter)} (#{(used[meter] / cap * 100).floor}%)",
+                 level: :warn)
+    end
+  end
+
+  # The counted work per meter: tool calls and active minutes, less the
+  # ignored tools' share.
+  def used(ctx, usage)
+    ignored = ignore_tools(ctx)
+    calls = usage.tool_calls - ignored.sum { |tool| usage.tool_calls_by_tool.fetch(tool, 0) }
+    active_ms = usage.active_ms - ignored.sum { |tool| usage.tool_ms_by_tool.fetch(tool, 0) }
+    { "tool_calls" => [calls, 0].max.to_f, "minutes" => [active_ms, 0].max / 60_000.0 }
+  end
+
+  # Once per session: the settings whose cap didn't read, and what is used.
+  def unreadable(ctx, resolved)
+    bad = resolved[:unreadable]
+    return if bad.empty? || !first_time?(:@unread_warned, resolved[:session])
+
+    named = bad.map { |key, value| "#{key}: #{value.inspect}" }.join(" and ")
+    used = resolved[:meters].values.filter_map do |meter_cap|
+      "#{meter_cap[:key]}: (#{count(meter_cap[:cap])})" if meter_cap[:cap]
+    end
+    using = used.empty? ? "no cap" : "using #{used.join(", ")}"
+    ctx.notify("work-cap: #{named} #{bad.size == 1 ? "isn't" : "aren't"} a number or off; #{using}", level: :warn)
+  end
+
+  def at_cap(ctx, resolved, reached, usage, used)
+    raised = reached.to_h do |meter, meter_cap|
+      [meter, raised_cap(meter_cap[:cap], meter_cap[:step] || meter_cap[:cap], used[meter])]
+    end
+    answer = ctx.ask_user(question: "Work cap reached: #{reached_text(reached, used)} (#{totals(ctx, usage, used, reached.keys)}). " \
+                                    "Continue raises #{raised_text(raised)}.",
+                          header: "Work cap", options: OPTIONS, effects: EFFECTS)
+    if continue?(answer)
+      raised.each do |meter, cap|
+        save_meter(ctx, resolved[:session], meter, "cap" => cap, "step" => reached[meter][:step] || reached[meter][:cap])
+      end
+      ctx.notify("#{raised.size == 1 ? "cap" : "caps"} raised to " \
+                 "#{raised.map { |meter, cap| "#{count(cap)} #{unit(meter)}" }.join(" and ")}")
+    else
+      stop(ctx, reached, usage, used)
+    end
+  end
+
+  # "412 tool calls of 400", and "61 active minutes of 60" for the other.
+  def reached_text(reached, used)
+    reached.map { |meter, meter_cap| "#{count(used[meter])} #{unit(meter)} of #{count(meter_cap[:cap])}" }.join(", ")
+  end
+
+  # "it to 800", or "them to 800 tool calls and 120 active minutes".
+  def raised_text(raised)
+    return "it to #{count(raised.values.first)}" if raised.size == 1
+
+    "them to #{raised.map { |meter, cap| "#{count(cap)} #{unit(meter)}" }.join(" and ")}"
+  end
+
+  # The session's totals a reader decides on, the reached meters left out
+  # (already named): turns, tool calls, active minutes and the spend.
+  def totals(ctx, usage, used, skip = [])
+    parts = ["#{usage.turns} #{usage.turns == 1 ? "turn" : "turns"}"]
+    parts << "#{count(used["tool_calls"])} tool calls" unless skip.include?("tool_calls")
+    parts << "#{active_text(used["minutes"])} active" unless skip.include?("minutes")
+    cost = ctx.cost
+    parts << format("$%.2f", cost.total) if cost.known? && cost.total.positive?
+    parts.join(", ")
+  end
+
+  # "47 min", or "<1 min" before a whole minute of work.
+  def active_text(minutes) = minutes < 1 ? "<1 min" : "#{count(minutes.floor)} min"
+
+  # Another step on the cap, as many steps as it takes to pass the work
+  # (a turn that overshot by more than a step asks once, not each step):
+  # Continue always leaves the cap past the work now.
+  def raised_cap(cap, step, used)
+    raised = cap + step
+    raised += step while raised <= used
+    raised.round(6)
+  end
+
+  def continue?(answer)
+    return false unless answer
+
+    Array(answer[:selected]).first == "Continue" || Array(answer[:selected_indices]).first&.zero?
+  end
+
+  def stop(ctx, reached, usage, used)
+    return unless ctx.stop_turn("work cap reached (#{reached_text(reached, used)})")
+
+    ctx.card(title: "work-cap stopped the turn",
+             body: "Used #{reached_text(reached, used)} (#{totals(ctx, usage, used, reached.keys)}).\n\n" \
+                   "`/workcap N` raises the tool-call cap, `/workcap Nm` the active minutes, `/workcap off` removes both.",
+             level: :warn)
+  end
+
+  def command(args, ctx)
+    arg = args.to_s.strip.downcase
+    return show(ctx) if arg.empty?
+
+    session = ctx.session_id
+    return "work-cap: no session yet" unless session
+
+    if %w[off 0].include?(arg)
+      METERS.each { |meter| save_meter(ctx, session, meter, "cap" => nil) }
+      return "work-cap: no cap for this session"
+    end
+    meter = arg.match?(NUMBER) ? "tool_calls" : "minutes"
+    value = self.class.amount(arg, meter)
+    return USAGE unless value
+
+    save_meter(ctx, session, meter, "cap" => value, "step" => value)
+    "work-cap: #{unit(meter)} cap set to #{count(value)} (#{count(used(ctx, ctx.usage)[meter])} so far)"
+  rescue StandardError => e
+    ctx.log.warn(:workcap_command_failed, error: "#{e.class}: #{e.message}")
+    "work-cap: #{e.message}"
+  end
+
+  def show(ctx)
+    usage = ctx.usage
+    used = used(ctx, usage)
+    meters = resolve(ctx)[:meters]
+    return "work-cap: no cap (#{totals(ctx, usage, used)})" if meters.values.none? { |meter_cap| meter_cap[:cap] }
+
+    capped = meters.select { |_meter, meter_cap| meter_cap[:cap] }
+    caps = capped.map { |meter, meter_cap| "#{count(used[meter])} of #{count(meter_cap[:cap])} #{unit(meter)}" }
+    "work-cap: #{caps.join(", ")} (#{totals(ctx, usage, used, capped.keys)})"
+  end
+
+  def unit(meter) = meter == "tool_calls" ? "tool calls" : "active minutes"
+
+  # The session's caps now: per meter the state file's, else the session's
+  # own value (--set), else child:'s for a delegate, else default:'s.
+  # Cached per session id.
+  def resolve(ctx)
+    session = ctx.session_id
+    cached = @mutex.synchronize { @resolved }
+    return cached if cached && cached[:session] == session
+
+    saved = state(ctx, session)
+    configured = configured(ctx)
+    meters = METERS.to_h { |meter| [meter, saved[meter] || configured[:meters][meter]] }
+    resolved = { session: session, meters: meters, unreadable: configured[:unreadable] }
+    @mutex.synchronize { @resolved = resolved }
+  end
+
+  # The state file's meters ({meter => {cap:, step:}}), {} without one.
+  def state(ctx, session)
+    return {} unless session
+
+    saved = JSON.parse(File.read(state_path(ctx, session)))
+    return {} unless saved.is_a?(Hash)
+
+    METERS.each_with_object({}) do |meter, meters|
+      entry = saved[meter]
+      next unless entry.is_a?(Hash) && entry.key?("cap")
+
+      cap = self.class.amount(entry["cap"], meter)
+      meters[meter] = { cap: cap, step: self.class.amount(entry["step"], meter) || cap, key: "/workcap" }
+    end
+  rescue Errno::ENOENT, JSON::ParserError
+    {}
+  end
+
+  # Per meter the first of its own value, child:'s (a delegate's) and
+  # default:'s that is set and reads (.readable?); the ones set that don't
+  # read (and a child:/default: that isn't a mapping) are kept for the
+  # notice (#unreadable).
+  def configured(ctx)
+    settings = ctx.settings
+    unreadable = {}
+    groups = %w[child default].select { |group| settings.key?(group) }
+    groups.delete("child") if groups.include?("child") && !ctx.delegate?
+    groups = groups.select do |group|
+      next true if settings[group].is_a?(Hash)
+
+      unreadable[group] = settings[group] unless settings[group].nil?
+      false
+    end
+    meters = METERS.to_h do |meter|
+      sources = [[meter, settings, meter]] + groups.map { |group| ["#{group}.#{meter}", settings[group], meter] }
+      [meter, first_readable(sources, unreadable)]
+    end
+    { meters: meters, unreadable: unreadable }
+  end
+
+  def first_readable(sources, unreadable)
+    sources.each do |name, values, meter|
+      next unless values.key?(meter)
+
+      value = values[meter]
+      unless self.class.readable?(value, meter)
+        unreadable[name] = value
+        next
+      end
+      cap = self.class.amount(value, meter)
+      return { cap: cap, step: cap, key: name }
+    end
+    { cap: nil, step: nil, key: nil }
+  end
+
+  def ignore_tools(ctx)
+    settings = ctx.settings
+    settings.key?("ignore_tools") ? Array(settings["ignore_tools"]).map(&:to_s) : DEFAULT_IGNORE
+  end
+
+  def warn_share(ctx)
+    settings = ctx.settings
+    return WARN_AT unless settings.key?("warn_at")
+
+    share = settings["warn_at"]
+    share.is_a?(Numeric) && share.positive? ? share : nil
+  end
+
+  # Write one meter's cap into the session's state file (the other kept).
+  def save_meter(ctx, session, meter, data)
+    path = state_path(ctx, session)
+    FileUtils.mkdir_p(File.dirname(path))
+    saved = begin
+      JSON.parse(File.read(path))
+    rescue Errno::ENOENT, JSON::ParserError
+      {}
+    end
+    saved = {} unless saved.is_a?(Hash)
+    saved[meter] = data
+    Samagotchi::AtomicFile.write(path, "#{JSON.generate(saved)}\n")
+    # Resolved again at the next use, from the file now holding the meter.
+    @mutex.synchronize { @resolved = nil }
+  end
+
+  def state_path(ctx, session) = File.join(ctx.data_dir, "sessions", "#{session.gsub(/[^A-Za-z0-9_.-]/, "_")}.json")
+
+  def count(value) = self.class.count(value)
+
+  def first_warning?(meter, key)
+    @mutex.synchronize do
+      next false if @warned[meter] == key
+
+      @warned[meter] = key
+      true
+    end
+  end
+
+  # Whether +key+ is new for the once-only notice kept in +ivar+ (and keep it).
+  def first_time?(ivar, key)
+    @mutex.synchronize do
+      next false if instance_variable_get(ivar) == key
+
+      instance_variable_set(ivar, key)
+      true
+    end
+  end
+end

data/lib/samagotchi/engine.rb

@@ -2680,7 +2680,8 @@ module Samagotchi
         # returns [] itself: the || keeps a nil builder safe).
         prompt_files: -> { @prompt_builder&.prompt_files || [] },
         frontend: -> { interface },
-        cost: -> { @metrics.cost }
+        cost: -> { @metrics.cost },
+        usage: -> { @metrics.usage }
       )
     end
 

data/lib/samagotchi/hooks/loader.rb

@@ -52,15 +52,21 @@ module Samagotchi
 
         # Load hooks from a config hash and return a Registry with registered plugins.
         #
-        # @param config_hash [Hash, nil] the hooks section from config.yml
+        # @param config_hash [Hash, nil] the parsed config.yml
         # @param env [Hash] environment variables (default: ENV)
         # @param failures [Guardrails::LoadFailures, nil] collects hooks that
         #   failed to load
         # @return [Samagotchi::Hooks::Registry] the registry with all plugins registered
         def load(config_hash, env: ENV, failures: nil)
-          return Hooks::Registry.new unless config_hash&.key?("hooks")
+          hooks_config = config_hash["hooks"] if config_hash.is_a?(Hash)
+          # An empty `hooks:` key is nil in YAML: no hooks, like no key.
+          return Hooks::Registry.new if hooks_config.nil?
+
+          unless hooks_config.is_a?(Hash)
+            Log.warn(:hooks, "hooks_section_invalid", echo: "[samagotchi:hooks] config.yml hooks: must be a mapping of event name to hook entries; ignored")
+            return Hooks::Registry.new
+          end
 
-          hooks_config = config_hash["hooks"]
           hooks_dir = hooks_dir(env, data: config_hash)
 
           registry = Hooks::Registry.new
@@ -92,10 +98,17 @@ module Samagotchi
 
       # Parse hook definitions from the config hooks section.
       # Returns an array of { event_type:, path:, on_error: } hashes.
+      # An event key that holds something other than a list warns and is
+      # skipped; an empty one (nil) is skipped silently.
       def self.parse_definitions(hooks_config)
         definitions = []
         hooks_config.each do |event_type, configs|
-          next unless event_type.to_s != "hooks_dir" && configs.is_a?(Array)
+          next if event_type.to_s == "hooks_dir" || configs.nil?
+
+          unless configs.is_a?(Array)
+            Log.warn(:hooks, "hooks_event_invalid", echo: "[samagotchi:hooks] config.yml hooks.#{event_type}: must be a list of hook entries; ignored", event: event_type.to_s)
+            next
+          end
 
           configs.each do |cfg|
             next unless cfg.is_a?(Hash) && cfg["path"]

data/lib/samagotchi/plugin/api.rb

@@ -40,7 +40,8 @@ module Samagotchi
         "ctx.prompt_files" => "0.60.0", "chi.annotation" => "0.66.0", "chi.toolkit" => "0.66.0",
         "ctx.use_toolkit" => "0.66.0", "ctx.toolkit" => "0.66.0", "ctx.declared_tools" => "0.66.0",
         "chi.tool_source" => "0.67.0", "chi.peer_source" => "0.67.0", "ctx.http" => "0.80.0",
-        "ctx.cost" => "0.83.0", "ctx.sessions.children" => "0.34.0", "ctx.load_tools" => "0.99.0"
+        "ctx.cost" => "0.83.0", "ctx.sessions.children" => "0.34.0", "ctx.load_tools" => "0.99.0",
+        "ctx.usage" => "0.100.0"
       }.freeze
 
       # @param bundle [String]

data/lib/samagotchi/plugin/context.rb

@@ -4,6 +4,7 @@ require "fileutils"
 require_relative "../log"
 require_relative "../paths"
 require_relative "../session_metrics/cost"
+require_relative "../session_metrics/usage"
 require_relative "../guardrails/context"
 require_relative "../hook_question"
 require_relative "../idle_client"
@@ -55,11 +56,12 @@ module Samagotchi
     # ctx.http call without cancel: uses, nil for none: an init task's own,
     # else the running turn's for work done for it (the turn's thread, or a
     # plugin handler: +handler+) until the turn has ended.
-    # +cost+ returns the session's spend now (SessionMetrics::Cost).
+    # +cost+ returns the session's spend now (SessionMetrics::Cost),
+    # +usage+ its work now (SessionMetrics::Usage).
     Host = Struct.new(:session_id, :cwd, :messages, :messages_partial, :notify, :ask_user, :cancelled, :card,
                       :ask_model, :model_name, :model_key, :state_dir, :scratch, :setup, :prompt_files,
                       :steer, :stop_turn, :stop_generation, :frontend, :toolkit, :declared_tools, :use_toolkit, :load_tools,
-                      :cancel_controller, :cost, keyword_init: true)
+                      :cancel_controller, :cost, :usage, keyword_init: true)
 
     # ctx.ask_model failed: the model couldn't be reached, timed out, or
     # sent nothing usable. The message says why, for the user.
@@ -167,6 +169,12 @@ module Samagotchi
       #   (docs/plugins.md); zero and known with no session
       def cost = @host.cost&.call || SessionMetrics::Cost.zero
 
+      # @return [SessionMetrics::Usage] the session's work so far, read now:
+      #   #turns, #tool_calls, #tool_calls_by_tool, #steps, #active_ms
+      #   (#active_minutes) and #tool_ms_by_tool (docs/plugins.md); zero
+      #   with no session
+      def usage = @host.usage&.call || SessionMetrics::Usage.zero
+
       # @return [String, nil] the name of the session's toolkit ("full" for
       #   one from before toolkits; nil with no session)
       def toolkit = @host.toolkit&.call

data/lib/samagotchi/session_metrics/usage.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Samagotchi
+  class SessionMetrics
+    # The session's work so far (SessionMetrics#usage, what a bundle's
+    # ctx.usage reads), across its turns and workers: the same numbers
+    # /stats and `chi sessions stats` show.
+    # +turns+: finished turns plus the running one. +tool_calls+ and
+    # +tool_calls_by_tool+ (canonical names: an alias counts under the tool
+    # it resolved to, a call_tool call under the inner tool): every call,
+    # running ones included. +steps+: the loop rounds that dispatched tools
+    # (the snapshot's iterations_total). +active_ms+: work time, the
+    # generations' time plus the finished tool calls' time (approval waits
+    # left out; ask_user_question's, a wait on the user, not counted),
+    # never a question's wait between them; +tool_ms_by_tool+ is the tool
+    # part by tool (the same names), so a reader can leave a waiting tool's
+    # time (task_wait, a blocking delegate) out.
+    # Bundles use its methods only, never this constant's name.
+    Usage = Data.define(:turns, :tool_calls, :tool_calls_by_tool, :steps, :active_ms, :tool_ms_by_tool) do
+      def self.zero = new(turns: 0, tool_calls: 0, tool_calls_by_tool: {}, steps: 0, active_ms: 0, tool_ms_by_tool: {})
+
+      # Data freezes itself, not its hashes: these are copied and frozen.
+      def initialize(tool_calls_by_tool:, tool_ms_by_tool:, **)
+        super(tool_calls_by_tool: tool_calls_by_tool.dup.freeze, tool_ms_by_tool: tool_ms_by_tool.dup.freeze, **)
+      end
+
+      # @return [Float] active_ms in minutes
+      def active_minutes = active_ms / 60_000.0
+    end
+  end
+end

data/lib/samagotchi/session_metrics.rb

@@ -14,6 +14,7 @@ require_relative "session"
 require_relative "session_metrics/totals"
 require_relative "session_metrics/model_segment"
 require_relative "session_metrics/cost"
+require_relative "session_metrics/usage"
 require_relative "session_metrics/side_totals"
 require_relative "side_usage"
 
@@ -53,6 +54,10 @@ module Samagotchi
     SPEED_MIN_TOKENS = 8
     SPEED_MIN_MS = 100
 
+    # The tools whose time is a wait on the user, not work (#usage).
+    USER_WAIT_TOOLS = %w[ask_user_question].freeze
+    private_constant :USER_WAIT_TOOLS
+
     # The session's token totals as a saved analytics.json has them (zeros
     # where an older file lacks a count), with how full the context was.
     # A generation's decode speed (tokens per second) and where it came
@@ -377,6 +382,23 @@ module Samagotchi
       @mutex.synchronize { Cost.of(@totals.with_running(@turn), @side) }
     end
 
+    # The session's work now (ctx.usage): turns, tool calls (by tool), steps
+    # and active (work) time, earlier workers' loaded records and the
+    # running turn included. Safe from any thread.
+    # @return [Usage]
+    def usage
+      @mutex.synchronize do
+        turn = @turn
+        totals = @totals.with_running(turn)
+        calls, by_tool = tool_call_counts(turn)
+        tool_ms = @tool_tallies[:ms]
+        # Finished calls only: a running call's approval wait isn't known
+        # until it completes (waited_ms), so its time counts then.
+        Usage.new(turns: turn_count(turn), tool_calls: calls, tool_calls_by_tool: by_tool, steps: totals.iterations,
+                  active_ms: (totals.gen_ms + tool_ms.values.sum).round, tool_ms_by_tool: tool_ms.transform_values(&:round))
+      end
+    end
+
     # Event sink. Safe to call from any thread; errors are isolated by the
     # caller (SessionObserver / TerminalUI) but we still guard internally.
     # @param event [Hash]
@@ -542,10 +564,10 @@ module Samagotchi
     def build_snapshot(records_mode)
       turn = @turn
       totals = @totals.with_running(turn)
-      in_flight = turn ? turn.tool_calls_by_id.values : []
+      calls, by_tool = tool_call_counts(turn)
       {
         session_id: @session_id,
-        turns: @turn_records.size + (turn ? 1 : 0),
+        turns: turn_count(turn),
         cancellations: totals.cancellations,
         tokens: totals.tokens_block,
         # The tokens, cost and speeds per model, in order (ModelSegment.rows:
@@ -557,8 +579,8 @@ module Samagotchi
         profile_source: @profile_source,
         served_model: @served_model,
         served_model_for: @served_model_for,
-        tool_calls_total: @tool_records.size + in_flight.size,
-        tool_calls_by_tool: tally_into(@tool_tallies[:by_tool].dup, in_flight),
+        tool_calls_total: calls,
+        tool_calls_by_tool: by_tool,
         # The calls the model made under an alias's name (bash run as
         # execute), by its own spelling; only when there are any.
         **(@tool_tallies[:aliased].empty? ? {} : { tool_calls_aliased: @tool_tallies[:aliased].dup }),
@@ -582,6 +604,17 @@ module Samagotchi
       }
     end
 
+    # The finished turns and the running one. Caller holds the mutex.
+    def turn_count(turn) = @turn_records.size + (turn ? 1 : 0)
+
+    # Every tool call (loaded records, this process's, the running ones)
+    # and the calls by tool, a copy. Caller holds the mutex.
+    # @return [Array(Integer, Hash)]
+    def tool_call_counts(turn)
+      in_flight = turn ? turn.tool_calls_by_id.values : []
+      [@tool_records.size + in_flight.size, tally_into(@tool_tallies[:by_tool].dup, in_flight)]
+    end
+
     # The model segments with the running turn in: the last one's when it
     # runs on that model or names none yet, else a new one. Caller holds
     # the mutex.
@@ -1199,7 +1232,8 @@ module Samagotchi
       @totals = Totals.zero
       @segments = []
       @last_model_ref = nil
-      @tool_tallies = { by_tool: {}, aliased: {}, errors: 0 }
+      # ms: the finished calls' time by tool (#usage's active_ms).
+      @tool_tallies = { by_tool: {}, aliased: {}, errors: 0, ms: {} }
     end
 
     def count_turn(record)
@@ -1219,6 +1253,15 @@ module Samagotchi
       tally_into(@tool_tallies[:by_tool], [record])
       called_as = record[:called_as].to_s
       @tool_tallies[:aliased][called_as] = @tool_tallies[:aliased].fetch(called_as, 0) + 1 unless called_as.empty?
+      count_tool_ms(record)
+    end
+
+    def count_tool_ms(record)
+      name = record[:tool].to_s
+      ms = record[:duration_ms]
+      return if name.empty? || !ms.is_a?(Numeric) || USER_WAIT_TOOLS.include?(name)
+
+      @tool_tallies[:ms][name] = @tool_tallies[:ms].fetch(name, 0) + ms
     end
 
     def tally_into(counts, tools)

data/lib/samagotchi/testing/host.rb

@@ -3,6 +3,7 @@
 require_relative "../cancellation_controller"
 require_relative "../plugin/context"
 require_relative "../session_metrics/cost"
+require_relative "../session_metrics/usage"
 require_relative "recorder"
 
 module Samagotchi
@@ -49,7 +50,8 @@ module Samagotchi
           use_toolkit: ->(name) { recorder.use_toolkit(name, toolkits.call) },
           load_tools: ->(names, bundle) { recorder.load_tools(names, bundle) },
           cancel_controller: ->(handler: false) { recorder[:cancelled] ? stopped : nil },
-          cost: -> { cost(recorder[:cost]) }
+          cost: -> { cost(recorder[:cost]) },
+          usage: -> { usage(recorder[:usage]) }
         )
       end
 
@@ -75,6 +77,33 @@ module Samagotchi
         else raise ArgumentError, "cost: a number, a Hash or a callable, not #{value.inspect}"
         end
       end
+
+      # The parts a test may give bundle.set(usage: {...}).
+      USAGE_PARTS = %i[turns tool_calls tool_calls_by_tool steps active_ms tool_ms_by_tool].freeze
+
+      # The SessionMetrics::Usage ctx.usage returns for the recorder's
+      # +usage+ value (Recorder::DEFAULTS): zeros for the parts not given;
+      # tool_calls defaults to the sum of tool_calls_by_tool, active_ms to
+      # the sum of tool_ms_by_tool.
+      # @return [SessionMetrics::Usage]
+      def usage(value)
+        value = value.call while value.respond_to?(:call)
+        case value
+        when nil then SessionMetrics::Usage.zero
+        when SessionMetrics::Usage then value
+        when Hash
+          parts = value.transform_keys(&:to_sym)
+          unknown = parts.keys - USAGE_PARTS
+          raise ArgumentError, "unknown usage parts: #{unknown.join(", ")}" unless unknown.empty?
+
+          by_tool = parts.fetch(:tool_calls_by_tool, {}).transform_keys(&:to_s)
+          ms_by_tool = parts.fetch(:tool_ms_by_tool, {}).transform_keys(&:to_s)
+          SessionMetrics::Usage.new(turns: parts.fetch(:turns, 0), tool_calls: parts.fetch(:tool_calls, by_tool.values.sum),
+                                    tool_calls_by_tool: by_tool, steps: parts.fetch(:steps, 0),
+                                    active_ms: parts.fetch(:active_ms, ms_by_tool.values.sum), tool_ms_by_tool: ms_by_tool)
+        else raise ArgumentError, "usage: a Hash or a callable, not #{value.inspect}"
+        end
+      end
     end
 
     # The hook runtime (Hooks::Runtime: event[:notify] and the other

data/lib/samagotchi/testing/recorder.rb

@@ -37,7 +37,11 @@ module Samagotchi
         prompt_files: [], cancelled: false, state_dir: nil, running: true, toolkit_staged: true, load_tools_staged: nil,
         # ctx.cost: nil (zero), a Float (reported USD), a Hash of the parts
         # (reported:, estimated:, side:, known:) or a callable giving one.
-        cost: nil
+        cost: nil,
+        # ctx.usage: nil (zero), a Hash of the parts (turns:, tool_calls:,
+        # tool_calls_by_tool:, steps:, active_ms:, tool_ms_by_tool:) or a
+        # callable giving one.
+        usage: nil
       }.freeze
 
       attr_reader :notices, :cards, :steers, :stops, :questions, :model_requests, :toolkit_uses, :tool_loads, :answers,

data/lib/samagotchi/version.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Samagotchi
-  VERSION = "0.99.0"
+  VERSION = "0.100.0"
   # Sent as the User-Agent of every HTTP request chi makes.
   USER_AGENT = "chi/#{VERSION}"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: samagotchi
 version: !ruby/object:Gem::Version
-  version: 0.99.0
+  version: 0.100.0
 platform: ruby
 authors:
 - Dmitry Dedov
@@ -266,6 +266,8 @@ files:
 - lib/samagotchi/bundles/system/manifest.yml
 - lib/samagotchi/bundles/system/memory_guide.md
 - lib/samagotchi/bundles/system/self_map.md
+- lib/samagotchi/bundles/work-cap/manifest.yml
+- lib/samagotchi/bundles/work-cap/plugin.rb
 - lib/samagotchi/cache_confirm.rb
 - lib/samagotchi/cancellation_controller.rb
 - lib/samagotchi/child_env.rb
@@ -523,6 +525,7 @@ files:
 - lib/samagotchi/session_metrics/model_segment.rb
 - lib/samagotchi/session_metrics/side_totals.rb
 - lib/samagotchi/session_metrics/totals.rb
+- lib/samagotchi/session_metrics/usage.rb
 - lib/samagotchi/session_model_settings.rb
 - lib/samagotchi/session_observer.rb
 - lib/samagotchi/session_retention.rb