@skein-code/cli 0.3.9 → 0.3.11

package/docs/ARCHITECTURE.md

@@ -82,13 +82,40 @@ 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.
+
 ## Local context selection
 
 The context boundary is deliberately in-process and local:
@@ -122,6 +149,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.9`.
+- Current repository version: `0.3.11`.
 - 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.9.tgz`. The verifier writes
-its SHA-256 to `artifacts/package/skein-code-cli-0.3.9.tgz.sha256`, and CI
+The latest verified package is `skein-code-cli-0.3.11.tgz`. The verifier writes
+its SHA-256 to `artifacts/package/skein-code-cli-0.3.11.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 37-file test suite passes the full check.
+40x10 short-height case. The current 42-file, 424-test suite passes the full check.
 
 ## Recommended Order
 
@@ -78,10 +78,13 @@ 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.9
-  refines the real four-stage context handoff, compact Skein welcome, and
-  grouped workspace rail. The startup readiness gate, runtime completion
-  evidence, and conservative dynamic-shell mutation tracking remain enforced.
+- The `main` branch rule requires the strict `check` status. Version 0.3.11
+  gives every tool-result path a language-aware dynamic token firewall, retains
+  complete captured output as redacted session-scoped artifacts, exposes
+  SHA-bound line or UTF-8 byte readback only when storage receipts agree, and
+  makes upstream shell/MCP truncation explicit. Session deletion and expiry
+  remove retained output; ordinary short result events keep their existing
+  shape.
   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.9",
+  "version": "0.3.11",
   "description": "A context-first, model-agnostic coding agent with an auditable terminal workspace.",
   "type": "module",
   "license": "MIT",
@@ -16,9 +16,9 @@
   },
   "skein": {
     "releaseNotes": [
-      "First-run context preparation now shows the real inspect, build, persist, and verify stages",
-      "Fresh sessions add a compact Skein identity and grouped workspace rail without filling the terminal",
-      "Short and narrow terminals collapse the index handoff while preserving validation and recovery states"
+      "Large tool results now use a language-aware dynamic token budget with status-preserving head and tail receipts",
+      "Complete captured output can be read back through redacted, expiring, session-scoped local artifacts",
+      "Shell and MCP source truncation is explicit, and session deletion removes retained output"
     ]
   },
   "bin": {