fix(ce-sessions): unblock session-history on Claude Code

[tmchow]

Summary

Session-history features (/ce-sessions and /ce-compound Phase 1) work on Claude Code again. Previously, the historian agent's first action was a Skill tool call to fetch session inventory, but Claude Code does not permit subagents to invoke the Skill tool (anthropics/claude-code#38719), so the spinner hung at Initializing… indefinitely and orchestrators received a spurious "user doesn't want to proceed" rejection.

The fix is structural: orchestration moves to the ce-sessions skill (main context, where the Skill tool works), and the historian becomes synthesis-only. It receives pre-extracted file paths in its dispatch prompt and reads them via the native file-read tool. No subagent ever invokes Skill again.

What changed

• ce-sessions is the canonical entry point. It owns the full pipeline: discovery, branch + keyword filtering, scan-window selection, top-5 deep-dive cap, scratch directory, per-session extraction, and synthesis dispatch. Scripts that were spread across ce-session-inventory/ and ce-session-extract/ now live in one home at plugins/compound-engineering/skills/ce-sessions/scripts/.
• ce-session-historian is synthesis-only. Receives {problem_topic, scratch_dir, sessions, output_schema}, reads the path files via the native file-read tool, returns prose findings. No Skill calls, no Bash discovery, no orchestration logic.
• ce-compound Phase 1 delegates via the platform's skill-invocation primitive in semantic-prose form (per ce-plan/references/plan-handoff.md line 57), not a literal Skill(...) tool-call expression. The literal form would propagate Claude-Code-specific syntax to Codex, Cursor, Gemini, OpenCode, Pi, and Kiro when the skill ships verbatim through the converters. Dispatch ordering is pinned: launch the three background research subagents first, then invoke ce-sessions, so wall-clock parallelism is preserved.
• Extract scripts gain --output PATH. When set, scripts write to file and emit only a one-line JSON status to stdout. Extraction content (~50 KB+ per session × 5 sessions) never round-trips through orchestrator tool results. Stdout-mode behavior preserved when the flag is omitted.
• Two callerless skills removed. ce-session-inventory and ce-session-extract were user-invocable: false script holders. With their callers gone, they're deleted and registered in STALE_SKILL_DIRS, LEGACY_ONLY_SKILL_DESCRIPTIONS, and EXTRA_LEGACY_ARTIFACTS_BY_PLUGIN so existing flat-installs sweep on upgrade.
• Regression test asserts the agent body never instructs Skill(ce-session-inventory), Skill(ce-session-extract), or any literal Skill(...) tool-call expression.

Why this shape

Issue #794 proposed two narrower fixes: refactor the agent to invoke scripts directly via Bash from subagent context, or have the orchestrator pre-fetch inventory and pass it into the subagent's dispatch prompt. Both leave Skill calls in subagent context (per-session extraction in Option B remains a Skill round-trip; Option A trips on the same script-path-resolution problem ce-sessions navigates, but agents have no sibling-scripts/ convention to lean on). This refactor moves every Skill call to main context, eliminating the deadlock structurally rather than working around it on a per-call basis. Full design rationale, alternatives considered, and implementation units are in docs/plans/2026-05-08-001-fix-ce-sessions-orchestration-refactor-plan.md.

Test plan

• 1337 bun tests pass (3 new --output PATH tests on the extract scripts; 4 new regression tests for the no-Skill-from-subagent invariant).
• bun run release:validate passes (49 agents, 37 skills after the two deletions).
• Manual smoke test on a marketplace-cached install (not --plugin-dir): /ce-sessions "what did we work on this week" and /ce-compound Full mode with session history opted in both complete without Initializing… hangs. The plan's Risks table flags an empirical verification step in case the bare bash scripts/... runtime invocation doesn't resolve from the skill directory; established slash-command precedents (ce-clean-gone-branches, ce-resolve-pr-feedback, ce-optimize) argue it does, but verifying on a real install before merge is cheap.

Post-Deploy Monitoring & Validation

• Watch for any new bug reports referencing Initializing… hangs on /ce-sessions or /ce-compound. The fix should eliminate them. If they recur, the architecture's central assumption (skill-invocation primitive works from inside an executing skill body in main context) is wrong and needs revisiting.
• Monitor for cross-platform regressions when the plugin converts and ships to Codex, Cursor, Gemini, OpenCode, Pi, and Kiro. The semantic-prose invocation form should round-trip cleanly through every converter; if a target's converter doesn't recognize the prose pattern, ce-compound's Phase 1 would silently skip session-history enrichment.
• Validation window: through next plugin release. Owner: plugin maintainers.

Closes #794.

---

[tmchow]

@digitalcostas wanna test this?

[digitalcostas]

Tested via marketplace-cached install of tmchow/debug-issue-794 on Claude Code, macOS Darwin 25.4.0. Plugin v3.7.0 / gitCommitSha: dd25db036c908b597b60e3cb242bec20abb9048a confirmed in ~/.claude/plugins/installed_plugins.json.

Install path

/plugin marketplace add https://github.com/EveryInc/compound-engineering-plugin.git#tmchow/debug-issue-794
/plugin install compound-engineering@compound-engineering-plugin

This routes through ~/.claude/plugins/cache/ like a published release — exercising the residual risk you flagged in the test plan, not just the diff. Filesystem verified: ce-session-inventory/ and ce-session-extract/ are absent from the skills cache; ce-sessions/scripts/ contains all 4 scripts.

Test 1: /ce-sessions "what did we work on this week"

✅ End-to-end success. 100 sessions inventoried (0 parse errors). 5 selected by size+recency+branch diversity, 3 returned substantive skeletons via the new --output PATH flag (status JSON to stdout, content to $SCRATCH/<id>.skeleton.txt). ce-session-historian subagent dispatched on sonnet, completed in 134s with 10 tool_uses (all file-reads, zero Skill calls in subagent context). Returned proper 4-section synthesis. No Initializing… hang.

The bare bash scripts/discover-sessions.sh runtime invocation resolved correctly from the marketplace-cached skill base dir — the residual risk you flagged in the test plan is empirically clear.

Test 2: /ce-compound Full mode + session-history opt-in

✅ End-to-end success on the path that previously deadlocked. The pinned dispatch ordering works as intended — background research subagents launched first (Context Analyzer 20s, Solution Extractor 51s, Related Docs Finder 91s), then Skill(ce-sessions) invoked from main context (~75s including historian dispatch on 4 sessions). Wall-clock for Phase 1 = max(~91s, ~75s) ≈ 91s, not 237s sequential — the parallelism preservation works.

End-to-end the skill produced a clean overlap-detected update to an existing learning doc, ran validate-frontmatter.py (exit=0), and completed Phase 2.5 + Discoverability without issue.

Separate pre-existing bug found during testing

Filed as #805 — extract-skeleton.py crashes with TypeError: unhashable type: 'slice' on one of five keyword-matched sessions due to a dict[:80] slice. Pre-existing (the consolidation moved the file, didn't re-author the code path) and doesn't block this merge.

Summary

LGTM from the original reporter. PR #800 fixes the deadlock structurally on Claude Code via marketplace-cached install. Will retire CLAUDE.md Rule 6 (the "answer no" workaround in our project rules) once plugin v3.7.0+ ships from a stable release.

Closes #794 confirmed working on this side.