@skein-code/cli 0.3.10 → 0.3.12

package/docs/ARCHITECTURE.md

@@ -34,8 +34,8 @@
 ## Agent turn
 
 1. Resolve `@path` mentions inside configured workspace roots.
-2. Ask the local context engine for task-relevant spans under the configured
-   token budget.
+2. Classify the task evidence surface and ask the local context engine for
+   task-relevant spans under an adaptive budget capped by configuration.
 3. Combine product rules, project rules, retrieved spans, mentions, current plan,
    and conversation history.
 4. Call the model with the tools allowed by the current mode.
@@ -43,8 +43,10 @@
 6. Create a checkpoint before the first mutation in a tool batch.
 7. Execute tools, emit events, and append their grounded results to the model
    conversation.
-8. Continue until the model returns a final response or the turn limit is hit.
-9. Run configured verification commands after changes. The completion gate accepts
+8. Record a bounded, content-free token receipt for the model request and
+   persist actual provider counters separately from local estimates.
+9. Continue until the model returns a final response or the turn limit is hit.
+10. Run configured verification commands after changes. The completion gate accepts
    only current successful test, typecheck, lint, build, check, or `git diff
    --check` evidence recorded after the last mutation. An early final response
    receives one bounded recovery turn; the runtime persists `verified`,
@@ -82,13 +84,56 @@ The runner keeps the cacheable system prefix separate from mutable task state:
 2. Dynamic turn state: intent directive, current plan, working memory, compacted
    handoff, workflow instructions, activated Skills, retrieved memories, and
    current code evidence.
-3. Conversation: recent user/assistant/tool messages, with old tool output
-   replaced by structured receipts when context pressure rises.
+3. Conversation: recent user/assistant/tool messages. Every new tool result is
+   bounded before it enters this layer; old tool output is replaced by compact
+   receipts when conversation pressure later triggers compaction.
 
 This lets providers reuse stable prompt prefixes while ensuring a changed plan
 or newly retrieved file is visible on the next turn. Every retrieved or generated
 state block is marked as untrusted context and cannot authorize a tool call.
 
+## Tool output boundary
+
+Tool output crosses three independent limits:
+
+1. Shell uses bounded capture and reports the stdout/stderr bytes it observed
+   and whether that limit omitted source bytes. After an MCP SDK call returns,
+   normalization applies a separate 5 MiB ceiling and preserves both ends. It
+   limits what reaches the runner; it does not sandbox the MCP process or bound
+   bytes already materialized by the transport.
+2. The runner sanitizes terminal control sequences, redacts credential-shaped
+   values, estimates CJK and non-CJK token cost, and derives a 1,024–8,192 token
+   model-visible budget from active context and remaining session headroom.
+3. If the sanitized captured result is complete and at most 5 MiB, the runner
+   can retain it outside the transcript. The model receives a head/tail receipt
+   with status, size, failure/exit/changed-file signals, hash, expiry, and a
+   bounded `read_tool_artifact` continuation.
+
+Artifacts are stored beneath the active project namespace, capped at 20 MiB in
+total, evicted oldest-first, and expired after seven days. File names are hashes
+of validated session/tool-call identities. Reads validate the session binding,
+file identity, byte count, and SHA-256; symlinks and corrupt records fail closed.
+At the start of a run, expired files are pruned and persisted session receipts
+are reconciled against storage before the readback tool can be exposed. Deleting
+a session removes its artifact directory. Session JSON and JSONL events carry
+only receipts and bounded previews, never artifact contents.
+
+## Token ledger and adaptive retrieval
+
+Each model request appends a maximum-256-entry token ledger to its session. A
+receipt contains only a request ID, turn, timestamp, partition counts, actual
+provider counters when present, measurement source, loaded tool names, and
+retrieval selection metadata. It never contains prompt text, workspace rules,
+source snippets, tool schemas, arguments, results, or credentials. Legacy
+sessions without provenance remain readable and are labelled `unknown` rather
+than being reported as actual usage.
+
+The local context ceiling is allocated by task shape: 2k for focused evidence,
+4k for ordinary work, 8k for cross-module or repository-wide work, and 12k only
+for explicitly exhaustive multi-part work. Each receipt reports its reason and
+the number of candidate, selected, overlapping, and budget-capped spans. These
+are estimated provider-neutral planning values, not billing claims.
+
 ## Local context selection
 
 The context boundary is deliberately in-process and local:
@@ -122,6 +167,8 @@ Project-local data is kept in `.mosaic/` and ignored by default:
 - `config.json` — project overrides;
 - `index.json` — local retrieval index;
 - `sessions/` — auditable conversation and tool state;
+- `tool-artifacts/` — redacted, expiring oversized tool results scoped to a
+  saved session;
 - `checkpoints/` — pre-mutation file snapshots and manifests.
 
 No source content is sent anywhere except the model endpoint selected by the

package/docs/NEXT_STEPS.md

@@ -9,7 +9,7 @@ one of the milestones below.
 
 - Product name: `Skein`; primary executable: `skein`.
 - Compatibility executables: `mosaic` and `mosaic-code`.
-- Current repository version: `0.3.10`.
+- Current repository version: `0.3.12`.
 - Runtime requirement: Node.js `>=22.16.0` (the runtime uses unflagged
   `node:sqlite` with FTS5, and current CLI/build dependencies require this
   Node 22 baseline).
@@ -41,8 +41,8 @@ npm audit --omit=dev
 npm run release:verify -- --output-dir artifacts/package
 ```
 
-The latest verified package is `skein-code-cli-0.3.10.tgz`. The verifier writes
-its SHA-256 to `artifacts/package/skein-code-cli-0.3.10.tgz.sha256`, and CI
+The latest verified package is `skein-code-cli-0.3.12.tgz`. The verifier writes
+its SHA-256 to `artifacts/package/skein-code-cli-0.3.12.tgz.sha256`, and CI
 retains the checksum beside the package metadata. The checksum is deliberately
 not copied into this packaged document because doing so would change the
 archive it describes.
@@ -50,7 +50,7 @@ archive it describes.
 The final verification included a fresh install and real PTY interaction for
 all three executable aliases, `/about`, a permission prompt, denial, and clean
 Ctrl+C exit. PTY coverage included 20, 24 ASCII, 40, 80, 120 columns and a
-40x10 short-height case. The current 40-file, 403-test suite passes the full check.
+40x10 short-height case. The current 42-file, 424-test suite passes the full check.
 
 ## Recommended Order
 
@@ -78,11 +78,12 @@ Implementation notes:
 - `npm run release:verify` reproduces the package from source, installs it into
   an isolated prefix, rejects packaged local state, and exercises `skein`,
   `mosaic`, and `mosaic-code`.
-- The `main` branch rule requires the strict `check` status. Version 0.3.10
-  adds durable Task Contracts for complex executable requests, binds acceptance
-  to successful audit evidence and current verification, and gives tool
-  failures stable classes, bounded retry budgets, repair hints, and identical-
-  call circuit breaking. Short requests keep the smaller tool surface.
+- The `main` branch rule requires the strict `check` status. Version 0.3.12
+  adds privacy-safe per-request token receipts, actual-versus-estimated usage
+  provenance, prompt partition accounting, and adaptive 2k/4k/8k/12k local
+  retrieval budgets. Session telemetry stores counts, tool names, selection
+  decisions, and discard reasons, never prompt, source, schema, argument, or
+  tool-result content.
   Its tag, GitHub verification, and npm publication use the same source commit.
 
 ### P1: Skein Storage Namespace And Migration

package/docs/PRODUCT.md

@@ -71,7 +71,7 @@ Sources:
 | Context | Local BM25/path/symbol index, visible startup build/validation gate, freshness checks, token packing, multi-root, `@file` mentions |
 | Models | OpenAI, Anthropic, Gemini, OpenAI-compatible endpoints |
 | Agent | Multi-turn tool loop, task plan, evidence-gated completion, automatic verification, ask-only mode |
-| Tools | Read, list, search, write, patch, shell, Git, context search, task updates |
+| Tools | Read, list, search, write, patch, shell, Git, context search, task updates, session-scoped oversized-result readback |
 | Trust | Workspace path boundary, allow/ask/deny policy, command rules, hooks, checkpoints |
 | Sessions | Local persistence, resume/latest, list/show/delete/export |
 | UX | Ink TUI, responsive branded welcome/workspace rail, action timeline, context telemetry, plan rail, inline permission band, interruption |
@@ -95,6 +95,12 @@ when a compatible endpoint omits token counters, clamps the provider output
 allowance to the remaining budget, and records skipped tool calls rather than
 leaving an incomplete assistant/tool message pair.
 
+Tool output has a separate budget. Oversized success and failure results retain
+the evidence needed to decide the next action without injecting the full log
+into every following model call. Complete captured output can be paged from a
+redacted, expiring, session-bound local artifact; upstream capture loss remains
+explicit and is never described as recoverable.
+
 That makes Skein particularly strong for individual developers, regulated
 teams, self-hosted environments, and tooling groups building their own agent
 workflows.

package/docs/PRODUCT_BENCHMARK.md

@@ -1,7 +1,7 @@
 # Skein Product Benchmark
 
 This is a capability and workflow comparison, not a claim that products use
-the same models or pricing. It was reviewed on 2026-07-22 against public
+the same models or pricing. It was reviewed on 2026-07-25 against public
 product documentation.
 
 ## Positioning
@@ -21,6 +21,7 @@ product surfaces.
 | Area | Mainstream signal | Skein today | Product implication |
 | --- | --- | --- | --- |
 | Context | Auggie automatically indexes projects and offers context-aware interactive and print modes. Its MCP Tool Search avoids loading every remote schema up front. See [Auggie overview](https://docs.augmentcode.com/cli/overview) and [integrations](https://docs.augmentcode.com/cli/integrations). | Local BM25/path/symbol retrieval with language-aware chunks, current-file freshness checks, diversity-aware token packing, progressive Skills, and hard token caps. MCP schemas are registered eagerly. | Benchmark local recall and latency by language, then make MCP tool discovery lazy and measurable. |
+| Tool result economy | FastCtx argues for structured file/search tools, explicit pagination, bounded output tiers, and persistent background-job logs so the model spends fewer turns on shell mechanics. See the [FastCtx repository](https://github.com/yc-duan/fastctx) and its [LINUX DO introduction](https://linux.do/t/topic/2612425). These are design signals, not independent evidence that every model becomes more accurate. | Native tools already use closed schemas and permission/checkpoint boundaries. Oversized results now use a dynamic token budget, head/tail receipts, source-truncation telemetry, and redacted session-scoped local readback. Single-file UTF-8 reads and foreground-only shell execution remain narrower than FastCtx. | Keep FastCtx optional through MCP instead of duplicating the default kernel. Add measured read/list/search continuation and batch reading before considering persistent background jobs. |
 | Workflow modes | Claude Code documents isolated subagents, agent teams, hooks, code intelligence, Skills, MCP, and plugins in one extension model. See [Claude Code extensions](https://code.claude.com/docs/en/features-overview). Copilot CLI exposes Plan and Autopilot modes. See [Copilot CLI](https://github.com/features/copilot/cli). | Ask and Build modes exist; Ask is read-only but does not produce a named approval-ready plan. | Add an explicit Plan mode. Keep it read-only and require approval before Build. |
 | Code intelligence | Claude Code advertises language-server-backed symbol navigation and live type errors. | Retrieval is lexical/BM25/path/symbol index based; no LSP diagnostics or rename graph. | Add an optional LSP adapter after storage and scheduler foundations. |
 | Parallel work | Claude documents isolated subagents and agent teams; Copilot CLI offers background delegation and fleet-style parallel work. | Routed multi-model councils share bounded reports, observe/guard/strict task-budget policies, reviewer acceptance/revision, and a responsive Team Cockpit. The main agent remains the only writer. | Add worktree-isolated writers, deterministic integration, and conflict/rollback UX without weakening the visible review gate. |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skein-code/cli",
-  "version": "0.3.10",
+  "version": "0.3.12",
   "description": "A context-first, model-agnostic coding agent with an auditable terminal workspace.",
   "type": "module",
   "license": "MIT",
@@ -16,9 +16,9 @@
   },
   "skein": {
     "releaseNotes": [
-      "Complex executable requests now use a durable Task Contract with evidence-bound acceptance criteria",
-      "Completion stays unverified while required acceptance or final verification remains unresolved",
-      "Structured tool failure receipts add concise repair hints, retry budgets, cancellation handling, and identical-call circuit breaking"
+      "Each model request records privacy-safe token partitions and actual-versus-estimated provenance",
+      "Local retrieval now selects focused, standard, broad, or maximum evidence budgets",
+      "Terminal and JSON diagnostics expose budget decisions without storing prompt or source content"
     ]
   },
   "bin": {