@skein-code/cli 0.3.26 → 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.26`.
+- 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.26.tgz`. The verifier writes
-its SHA-256 to `artifacts/package/skein-code-cli-0.3.26.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
@@ -414,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/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.26",
+  "version": "0.3.27",
   "description": "A context-first, model-agnostic coding agent with an auditable terminal workspace.",
   "type": "module",
   "license": "MIT",
@@ -16,6 +16,13 @@
   },
   "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",