@skein-code/cli 0.3.25 → 0.3.27

package/docs/ARCHITECTURE.md

@@ -289,21 +289,37 @@ JavaScript plugins are intentionally unsupported because they would share the
 CLI's full filesystem, environment, and process privileges.
 
 MCP is the interoperability boundary for external executable capabilities. It
-is disabled by default, removed from untrusted project configuration, exposes a
-compact lazy activation catalog during normal chat startup, treats server
-annotations as untrusted, and applies argument, schema, result, server-count,
-timeout, and transport limits. The `mcp_activate` catalog connects a selected
-server on demand, discovers its remote tools, and registers at most eight
-request-relevant schemas into the live registry; explicit diagnostic commands
-such as `skein mcp status` can still connect all configured servers eagerly.
-Every MCP activation and remote MCP call currently requires the network
-permission category. A configured stdio server is still an external program
-with the user's operating-system privileges; cwd and environment validation
-reduce accidental exposure but are not a sandbox. Only reviewed user-owned
-configuration should enable one.
-
-Before any marketplace-style plugin support, add a declarative capability
-manifest, first-run review, lazy tool-schema activation, per-server permission
-scopes, and an optional process sandbox. Plugin packages should compose Skills,
-workflows, and MCP servers rather than load arbitrary code into the Skein
-process.
+is disabled by default, removed from untrusted project configuration, treats
+server annotations as untrusted, and applies argument, schema, result,
+server-count, timeout, and transport limits. A common declarative capability
+vocabulary describes source, version, tools, permission categories, network,
+commands, paths, sensitive fields, background/process-tree effects, and
+completion-evidence support. Tool definitions carry the same source,
+activation, permission, and evidence metadata so `/tools` can distinguish the
+built-in, memory, workflow, agent, and MCP surfaces.
+
+Normal chat exposes three bounded controls: `mcp_search` and `mcp_inspect` read
+only local redacted manifests; `mcp_activate` connects only a manifest whose
+workspace-bound SHA-256 fingerprint the user trusted. The model cannot write
+the trust store. Remote discovery stays true-lazy and activation registers at
+most eight query-relevant schemas. Once a manifest names tools, undeclared
+remote schemas are rejected. Disable and revoke decisions persist and unload
+registered adapters. Optional server failures remain isolated; only an
+explicitly required, trusted server is checked during runtime initialization
+and allowed to block it.
+
+Every MCP call retains `network` permission even for stdio. Declared write,
+shell, and Git effects add rather than replace permission categories. Sensitive
+argument fields are redacted before terminal, TUI, JSON, or approval events.
+External mutations receive complete change tracking only when Skein created the
+pre-call checkpoint and the server returns that exact id with workspace-valid
+changed files, artifact receipts, and completion evidence. Other mutation
+results set tracking to `unresolved`, preventing an unsupported completion
+claim.
+
+A configured stdio server is still an external program with the user's
+operating-system privileges; cwd and environment validation are not a process
+sandbox. Marketplace-style packages must compose data-only Skills, workflows,
+profiles, and explicitly trusted MCP servers rather than load arbitrary code
+into the Skein process. An optional OS/container subprocess sandbox remains a
+future hardening layer.

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.25`.
+- Current repository version: `0.3.27`.
 - 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.25.tgz`. The verifier writes
-its SHA-256 to `artifacts/package/skein-code-cli-0.3.25.tgz.sha256`, and CI
+The latest verified package is `skein-code-cli-0.3.27.tgz`. The verifier writes
+its SHA-256 to `artifacts/package/skein-code-cli-0.3.27.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.
@@ -99,15 +99,13 @@ firewall policies while requiring complete evidence and recovery coverage.
 The replay reports a 36.7% estimated-input reduction; this is a deterministic
 budget measurement, not a provider billing or task-success claim.
 
-MCP tool definitions are now marked for progressive disclosure. Normal chat
-startup exposes a compact `mcp_activate` catalog instead of connecting every
-server. Selecting a configured server connects it, runs remote `listTools`, and
-loads at most eight request-relevant schemas into the live registry. Selected
-schemas retain their registry order and remain loaded for the current run, and
-Token Ledger receipts record the deferred count. MCP activation and discovered
-tools remain `network` operations, hidden tool calls remain rejected by the
-existing boundary, and explicit diagnostics such as `skein mcp status` still
-connect eagerly by design.
+MCP tool definitions use progressive disclosure. Version `0.3.23` exposed a
+compact `mcp_activate` catalog instead of connecting every server, then loaded
+at most eight request-relevant schemas. Version `0.3.27` adds the preceding
+local `mcp_search` and `mcp_inspect` stages plus user-owned fingerprint trust;
+`skein mcp status` is now no-connect. Selected schemas remain stable for the
+current run, Token Ledger receipts record the deferred count, MCP calls retain
+the network boundary, and hidden tool calls remain rejected.
 
 Version `0.3.22` normalizes provider-reported cache and reasoning usage across
 streaming and non-streaming OpenAI, Anthropic, and Gemini responses. Token
@@ -150,6 +148,29 @@ clarification and resume afterward; text, JSON, and JSONL expose the same
 `needs_input` state. Real same-model success/token A/B remains an external
 validation gate rather than an implied claim of this release.
 
+### Phase 2: First-run, permission, recovery, review, and headless contracts (complete in 0.3.26)
+
+Version `0.3.26` makes the first-run screen explicit that the primary agent
+uses API credentials while provider subscription sessions and signed-in coding
+CLIs remain separate delegated tools. Permission prompts now show the runtime
+policy reason, redacted target, working directory, category risk, and all four
+keyboard outcomes without leaking secrets.
+
+The interactive Recovery Center joins last-run status, content-free failure
+repair hints, changed files, checkpoints, diff, audit, rollback, bounded retry,
+and safe resume. `/review` fixes working-tree, commit, or branch scope, forces
+read-only runner capabilities even from Build mode, and injects a redacted
+content-free evidence bundle as ephemeral turn instructions rather than user
+transcript. Pending clarifications must still be answered directly and cannot
+be consumed by a recovery command.
+
+JSON and JSONL terminal records follow `docs/headless-output.schema.json` v1
+and carry stable statuses plus exit codes for completed/verified, runtime error,
+needs input, unverified, verification failed, blocked, cancelled, max turns,
+and token budget. Text and TUI surfaces provide matching actionable stop and
+recovery guidance. Responsive list clipping keeps the Recovery Center bounded
+in narrow and short terminals.
+
 ### P0-D: Repository reuse and calibrated duplication enforcement
 
 Version `0.3.14` added the prompt ladder and pre-write `ReuseReceipt`. Version
@@ -391,17 +412,29 @@ Implementation progress:
   Team Run compatibility. Parallel writers, external CLI writer mode, cost
   controls, Gemini CLI, and optional tmux/iTerm pane hosts remain next.
 
-### P2: MCP, Skills, And Workflow Trust UX
-
-Add a first-run catalog and inspection flow for bundled capabilities. Keep
-installation explicit and reviewable: show source, requested tools, filesystem
-scope, network scope, and trust state before activation. Add fixture servers and
-Skills that exercise timeout, malformed schema, disconnect, and version drift.
-Lazy MCP activation is now the default chat path. Next, add declarative
-capability manifests, per-server trust review, activation telemetry, and an
-optional subprocess sandbox before any marketplace. Do not load arbitrary plugin
-JavaScript in-process; package reusable extensions as data-only Skills/workflows
-plus explicitly trusted MCP servers.
+### P1: MCP capability trust (complete in 0.3.27)
+
+Version `0.3.27` completes local `search → inspect → trust → activate` for MCP.
+Redacted manifests cover source, version, tools, permission categories,
+network, commands, paths, sensitive fields, background/process-tree effects,
+and completion-evidence support. Trust is bound to the exact manifest
+fingerprint and workspace; the model cannot grant it. Persistent disable and
+revoke unload activated schemas. Optional server failures remain isolated and
+only explicitly required servers may block initialization.
+
+Declared permissions are additive to the non-removable network boundary, and
+server annotations cannot lower them. A named manifest rejects undeclared
+server-injected tools. Text, JSON, and TUI events redact declared sensitive
+arguments. External mutations stay completion-unresolved unless Skein's own
+checkpoint id, workspace-valid changed files, artifact receipts, and completion
+evidence round-trip successfully. Fixed tests cover malformed schemas,
+injection, trust invalidation, disable/revoke, required degradation, schema
+token savings, and top-tool selection. These are deterministic contract tests,
+not a general real-model accuracy claim.
+
+Future extension work may add an optional subprocess sandbox and data-only
+bundles that compose Skills, workflows, profiles, and trusted MCP servers. It
+must not load arbitrary plugin JavaScript in-process.
 
 ### Delivered: bounded long-session continuity and intent sufficiency
 

package/docs/PRODUCT_BENCHMARK.md

@@ -20,12 +20,12 @@ 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. Normal chat startup exposes only a compact `mcp_activate` server catalog; remote MCP connection, `listTools`, and up to eight relevant schemas are loaded on demand. | Measure lazy MCP activation cost and add per-server trust review/sandboxing before marketplace-style plugin support. |
+| 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 uses local `search → inspect → trust → activate`; remote `listTools` stays lazy and at most eight relevant schemas load. Activation receipts compare eager and selected schema estimates plus the lexical top match. | Keep the deterministic schema/selection fixture and add real-model tool-choice evaluation before claiming general accuracy gains. |
 | 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. |
-| Trust and execution | Gemini CLI documents sandboxing and trusted folders; Claude exposes lifecycle hooks and permission events. See the [Gemini CLI repository](https://github.com/google-gemini/gemini-cli) and [Claude hooks](https://code.claude.com/docs/en/hooks). | Category permissions, project trust, checkpoints, hooks, and audit trails are strong; process sandboxing and first-run trust inspection are incomplete. | Explain trust before activation and offer an optional OS/container sandbox. |
+| Trust and execution | Gemini CLI documents sandboxing and trusted folders; Claude exposes lifecycle hooks and permission events. See the [Gemini CLI repository](https://github.com/google-gemini/gemini-cli) and [Claude hooks](https://code.claude.com/docs/en/hooks). | Category permissions, project trust, checkpoints, hooks, audit trails, per-manifest MCP trust review, persistent disable/revoke, sensitive-field redaction, and unsupported-mutation evidence degradation are present. Process sandboxing remains incomplete. | Add an optional OS/container sandbox without weakening manifest, permission, or completion-evidence gates. |
 | Collaboration | Auggie supports integrations and conversation export; Copilot supports GitHub-native MCP and shareable workflows. | Session export and resumability are local; no shareable artifact or review bundle. | Add a deterministic redacted session/review bundle before any hosted sharing. |
 | Distribution and recovery | Competitors provide guided installation, auth, update channels, and workflow-specific entry points. | Package/release verification is reproducible; `skein doctor` reports project/user namespace and interrupted-operation state, while shared live-process leases and exclusive mutation leases make migration, rollback, and recovery crash-safe without deleting changed canonical data. | Add capability review and upgrade UX, then define the measured legacy-alias window. |
 
@@ -43,9 +43,9 @@ product surfaces.
    quarantining the canonical copy; `--recover` handles interrupted operations;
    `--home` covers user-level state. Shared leases cover live managed writers,
    while namespace mutation requires an exclusive crash-released lease.
-4. **P1 MCP trust hardening:** add per-server review, capability manifests,
-   activation telemetry, and optional stdio sandboxing on top of lazy MCP
-   activation.
+4. **P1 MCP trust hardening:** per-server review, capability manifests,
+   activation telemetry, persistent revoke, and required-server isolation are
+   delivered; optional stdio sandboxing remains.
 5. **P1 scheduler and isolation:** retain the shipped task-budget telemetry and
    reviewer loop, then add cancellation propagation, deterministic integration,
    and single-writer/worktree boundaries.

package/docs/headless-output.schema.json

@@ -0,0 +1,36 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://skein.dev/schemas/headless-output-v1.json",
+  "title": "Skein headless terminal record v1",
+  "description": "The terminal object emitted by --output-format json or as the final line of --output-format stream-json.",
+  "type": "object",
+  "required": ["schemaVersion", "type", "ok", "status", "exitCode", "reason"],
+  "properties": {
+    "schemaVersion": {"const": 1},
+    "type": {"enum": ["result", "session", "final"]},
+    "ok": {"type": "boolean"},
+    "status": {
+      "enum": [
+        "completed",
+        "verified",
+        "needs_input",
+        "unverified",
+        "verification_failed",
+        "blocked",
+        "cancelled",
+        "max_turns",
+        "token_budget",
+        "error"
+      ]
+    },
+    "exitCode": {"type": "integer", "minimum": 0, "maximum": 8},
+    "reason": {"type": "string", "minLength": 1},
+    "response": {"type": "string"},
+    "error": {"type": "string"},
+    "session": {"type": "object"},
+    "completion": {"type": "object"},
+    "context": {"type": "object"},
+    "tools": {"type": "array"}
+  },
+  "additionalProperties": true
+}

package/examples/config.yaml

@@ -58,3 +58,33 @@ ui:
   color: true
   compact: false
   theme: auto
+
+# External capabilities are disabled until both configuration and the separate
+# workspace-bound manifest trust review are explicit. Use:
+#   skein mcp search docs
+#   skein mcp inspect docs
+#   skein mcp trust docs
+#   skein mcp activate docs search documentation
+mcp:
+  enabled: false
+  connectTimeoutMs: 12000
+  toolTimeoutMs: 60000
+  servers:
+    docs:
+      enabled: false
+      required: false
+      transport: http
+      url: https://docs.example.com/mcp
+      description: Search approved documentation.
+      version: 1.0.0
+      tools:
+        - name: search
+          description: Search the approved documentation corpus.
+          permissions: [read]
+          network: [https://docs.example.com]
+          commands: []
+          paths: []
+          sensitiveFields: [token]
+          background: false
+          processTree: false
+          completionEvidence: none

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skein-code/cli",
-  "version": "0.3.25",
+  "version": "0.3.27",
   "description": "A context-first, model-agnostic coding agent with an auditable terminal workspace.",
   "type": "module",
   "license": "MIT",
@@ -16,6 +16,19 @@
   },
   "skein": {
     "releaseNotes": [
+      "MCP now follows a no-network search and inspect review before explicit workspace-bound manifest trust and lazy activation",
+      "Declarative capability manifests expose redacted source, version, tools, permissions, network, command, path, sensitive-field, process, and completion-evidence effects",
+      "Persistent disable and revoke unload active remote schemas while manifest fingerprint changes fail closed to untrusted",
+      "Server annotations cannot lower local permissions, named manifests reject injected undeclared schemas, and optional server failures remain isolated",
+      "Only explicitly required trusted MCP servers may block startup, while status inspection no longer connects optional servers",
+      "Sensitive MCP arguments are redacted from terminal, TUI, JSON, and approval events; unsupported external mutations remain completion-unresolved",
+      "Explain and review intents expose smaller built-in schema sets, and MCP activation reports deterministic eager-versus-loaded schema estimates plus top-match evidence",
+      "First-run setup now states that the primary agent needs API credentials and that provider subscriptions or signed-in coding CLIs are separate delegated tools",
+      "Permission prompts show the policy reason, redacted target, working directory, category risk, and explicit once, session, deny, and stop choices",
+      "The Recovery Center joins last-run state, failure repair hints, changed files, checkpoints, diff, audit, rollback, retry, and safe session resume",
+      "Read-only review commands pin working-tree, commit, or branch scope and inject a content-free redacted evidence bundle without storing it in the user transcript",
+      "JSON and JSONL terminal records now follow the published headless v1 schema with stable completed, verification, input, blocked, cancellation, turn, token, and error exit codes",
+      "Short terminal viewports clip long lists without overflow and pending clarifications cannot be consumed by recovery commands",
       "Durable sessions now separate a 250k-token context epoch from a 1m-token lifetime ceiling without changing the session id or deleting transcript history",
       "Content-free epoch handoffs preserve Task Contract criteria, unresolved failure circuits, changed files, and verification receipts across long runs",
       "Intent Sufficiency routes clear requests to execution, repository-inferable gaps to inspection, and genuine product choices to one persisted clarification",