[ytspar]

Simple Description

This hardens the public Enrich Layer fork of ctx for analyzing untrusted agent transcripts. It makes networked and executable behavior opt-in, limits default search and MCP access to a validated Git worktree, and clearly marks transcript-derived output as untrusted data. It also closes upgrade, model-cache, export, and MCP-configuration trust gaps found during adversarial review.

Closes DEV-5902.

What Changed

• made analytics, background upgrades, daemon maintenance, semantic search, and automatic history-source plugin execution opt-in
• scoped search and project MCP servers to a canonical Git worktree validated by Git itself; broad access requires explicit flags
• labeled transcript-derived text and structured output as untrusted, neutralized terminal/bidirectional controls, and made exports private and symlink-safe
• restricted automatic plugins to the private ctx plugin directory; custom data roots require an explicit unsafe CLI flag
• pinned semantic model acquisition to an immutable official revision with file sizes and SHA-256 hashes, then parses the same verified bytes
• restricted release endpoint/key/artifact overrides to explicit unsafe foreground upgrade flows
• pinned MCP integrations to an absolute executable, reduced scoped MCP to status/search, and made legacy migration exact-shape only
• hardened the bundled agent skill against prompt injection and removed remote pipe-to-shell installation instructions

Why This Change

The upstream tool indexes highly sensitive local transcripts and is intended to be called by agents that may encounter prompt-injection payloads inside those transcripts. Its prior defaults could send analytics, check/apply upgrades, acquire models, execute plugins, expose cross-workspace data, or present transcript text without a strong trust label. This fork needs a fail-closed local-analysis posture before it is suitable for Enrich Layer use. See DEV-5902.

Alternatives Considered

• removing all network features entirely: rejected because explicitly requested upgrades and pinned local semantic model acquisition remain useful; they are now off by default and constrained to trusted endpoints/artifacts
• removing plugin support entirely: rejected because explicit plugin imports are useful; automatic execution now needs reviewed config, a trusted default data root, and no environment discovery
• treating output escaping as a complete prompt-injection defense: rejected because transcript instructions remain semantically hostile; output is labeled/delimited as untrusted and the agent skill enforces a separate behavioral boundary
• allowing any absolute directory as a workspace scope: rejected because parent directories can aggregate multiple repositories; exact scopes must be real Git worktree roots

Testing Instructions

1. Run TMPDIR=/private/tmp cargo test --workspace -- --test-threads=1.
2. Run cargo clippy --workspace --all-targets --locked -- -D warnings -A dead-code.
3. Run bash scripts/check-docs.sh and git diff --check.
4. Spot-check ctx search --help, ctx mcp serve --help, and the new security documentation.

Expected Result: All tests and checks pass. Search fails closed outside a Git worktree unless --all-workspaces is explicit; scoped MCP exposes only status/search; networked and plugin behavior remains disabled by default.

Loom Video (if applicable): Not applicable; no UI changes.

AI observations

The adversarial review ran multiple focused passes and found boundary bypasses in synthetic scope markers, custom data-root plugin execution, semantic cache verification/use, legacy MCP migration, and a debug-only all-workspaces hook. Each finding was fixed with regression coverage; the final focused re-review returned PASS. The PR-template guard rejected the initial non-template body, so this description was rewritten into the required review structure.

Additional Context

Residual boundaries are explicit:

• prompt injection cannot be made trustworthy by escaping alone; agent behavior must continue treating transcript content as data, never instructions
• workspace filtering trusts normalized workspace/cwd metadata produced by local importers, so a malicious local importer can forge that metadata
• direct CLI show, locate, and read-only SQL remain broader capabilities; scoped MCP intentionally excludes them
• fastembed is Linux-targeted, so CI provides the target-specific compile check; local macOS checks cover the non-fastembed path

The changed diff passed gitleaks. Strict clippy is clean with only the repository's existing macOS platform-gated dead-code category allowed.

Checklist

• Self-review completed
• Loom/screenshots not applicable (no UI change)
• Documentation updated
• Linear issue linked in description and title