@skein-code/cli 0.3.10 → 0.3.12

package/README.md

@@ -43,6 +43,14 @@ inspectable index for code retrieval and no retrieval service dependency.
   source spans, and rebuild it explicitly when needed.
 - **Visible trust:** per-category permissions, deny rules, hooks, workspace path
   enforcement, changed-file telemetry, and persisted tool results.
+- **Bounded tool context:** large tool results cannot crowd the task out of the
+  model window. Skein keeps a token-budgeted head/tail receipt and, when the
+  producer captured the complete result, retains a redacted session-scoped
+  artifact for bounded readback.
+- **Measurable token economy:** every model request records a privacy-safe
+  receipt for stable, dynamic, history, retrieval, tool-result, and tool-schema
+  estimates, alongside actual provider usage when available. Receipts retain
+  only counts and runtime decisions, never prompt or source content.
 - **Reversible work:** Skein snapshots affected files before mutation without
   touching your Git history.
 - **Resumable by default:** conversations, tasks, usage, and changed files live
@@ -78,7 +86,7 @@ To build, verify, and install a local package artifact from this checkout:
 
 ```bash
 npm run verify:package -- --output-dir artifacts/package
-npm install -g ./artifacts/package/skein-code-cli-0.3.10.tgz
+npm install -g ./artifacts/package/skein-code-cli-0.3.12.tgz
 ```
 
 To install the published package from npm:
@@ -183,6 +191,19 @@ compacted session summary, and durable retrieval layer separately. Model-
 suggested durable memories can be reviewed with `/memory candidates` and then
 approved or rejected.
 
+Tool output has three explicit boundaries. Shell capture is bounded while the
+process runs; completed MCP responses are reduced to a 5 MiB adapter result
+before entering the runner. This MCP boundary limits transcript amplification,
+but it is not a process sandbox or a streaming transport limit. The runner then
+uses the remaining session/context headroom to expose at most 1,024–8,192
+estimated tokens to the model. An oversized result becomes a head/tail receipt
+that preserves completion or failure state, exit code, changed files, original
+size, and a SHA-256-bound `read_tool_artifact` continuation when the complete
+captured result is available. Artifacts are redacted before persistence, belong
+only to the originating session, expire after seven days, and are removed when
+that session is deleted. A receipt marked `source-truncated` is honest about
+bytes already omitted by the producing tool; those bytes cannot be recovered.
+
 At 96 columns and wider, a fresh session uses a two-column welcome surface. The
 left side keeps Skein's brand, workspace path, and next actions close to the
 composer; the right side reports the actual model, mode, local index file/chunk
@@ -387,6 +408,12 @@ are stale, moved, symlinked, binary, or outside the workspace. Retrieval is
 evidence only: the model must still confirm factual claims with read or other
 workspace tools.
 
+Retrieval budgets are adaptive and treat `context.maxTokens` as a ceiling:
+focused requests start at 2k estimated tokens, ordinary implementation/debug
+work at 4k, cross-module work at 8k, and only explicit exhaustive repository
+work can use 12k. The context receipt reports the chosen tier, reason, candidate
+and selected hit counts, overlap drops, and evidence above the focused base.
+
 To measure a local index change, run the reproducible benchmark with an explicit
 query-to-relevant-file manifest:
 
@@ -499,8 +526,11 @@ Add both `.mosaic/` and `.skein/` to `.gitignore` unless the team intentionally
 shares a sanitized configuration file elsewhere.
 
 Session JSON also keeps a bounded audit trail of permission decisions, tool
-outcomes, changed files, and checkpoint ids. `skein session export` includes
-that trail in the Markdown export.
+outcomes, changed files, checkpoint ids, and artifact receipts, never artifact
+contents. `skein session export` includes the audit trail in the Markdown
+export. Oversized result contents live separately under the active project
+namespace's `tool-artifacts/` directory and are governed by session deletion,
+expiry, per-item size, total-storage, and integrity checks.
 
 ## Development