feat: CSA-lite Phase 1 — caller session auto-detection + fork-from-caller (#1432)#1443
Merged
Merged
Conversation
…1432) Adds CallerSessionInfo and detect_caller_session() to csa-session for Phase 1 of CSA-lite fork. The detector first checks the CLAUDE_SESSION_ID env var (zero-cost path) and falls back to a xurl_core query for the latest Claude thread on disk. Returns None gracefully on any failure. - New caller_detect module with CallerSessionInfo struct and detect_caller_session() entry point - Re-exports both names from csa-session lib root - Adds xurl-core workspace dep to csa-session - 5 unit tests covering env-set+valid, env-set+missing, env-empty, env-unset, and nonfile-path rejection - Bumps workspace version to 0.1.733 - Stages stale weave.lock alongside the feature per AGENTS.md rule 055 Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Adds `PrefixExtractor` (with `PrefixConfig` / `ExtractedPrefix`) to `csa-acp` for reading a Claude Code JSONL session file and producing a token-budgeted conversation prefix suitable for injection into a forked session. This is Task 2 of CSA-lite Phase 1; Task 1 (caller session auto-detection in `csa-session::caller_detect`) supplies the `jsonl_path` consumed here. Behavior: - Only top-level `user`/`assistant` entries are surfaced; progress, system, and API-error entries are skipped. - When `skip_tool_results` is true (default), `tool_use` and `tool_result` content blocks are filtered, as are string-content messages with `role == "tool"`. - Token budget is enforced via a `words * 4 / 3` heuristic that mirrors `csa-session::output_parser::estimate_tokens` (inlined to avoid pulling csa-session into the L3 transport crate). - Malformed JSON lines are logged via `tracing::debug!` and skipped rather than aborting the extraction. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Task 3 of CSA-lite Phase 1: introduce a persisted config key for the fork prefix token budget consumed by csa-acp::PrefixExtractor. The field is Option<u32> on SessionConfig with serde default None; SessionConfig::resolved_fork_prefix_budget() returns 32_768 (the value mirrored from csa-acp::DEFAULT_PREFIX_BUDGET_TOKENS) when unset and clamps configured values into [4096, 131072]. Validation emits a user-visible warning for out-of-range values without failing config load, matching the existing warn_unknown_tool_priority pattern. Constants DEFAULT_FORK_PREFIX_BUDGET_TOKENS, FORK_PREFIX_BUDGET_MIN_TOKENS, FORK_PREFIX_BUDGET_MAX_TOKENS are re-exported from the crate root so downstream callers (csa-session fork wiring, future tasks in #1432) can reference them without duplicating literals. The global config template gains a commented [session] block with the key + range hint for discoverability. Why duplicate the default constant from csa-acp instead of importing it: csa-acp depends on csa-config (not vice versa), so an import edge would invert the layered crate graph (L1 -> L3).
Task 4 of CSA-lite Phase 1 fork session. Adds the `--fork-from-caller` flag to `csa run`, mutually exclusive with `--session`, `--last`, `--fork-from`, `--fork-last`, and `--ephemeral`. The flag is plumbed through `Commands::Run` destructuring, `GoalRunRequest`, and the `handle_run()` call chain. Resolution is wired in a follow-up commit; this commit only accepts the flag and emits a placeholder warn. Tests cover CLI parsing, default value, pairwise conflicts with each mutually-exclusive flag, and help-text rendering. The `use Duration` inline at the auto-weave-upgrade block was hoisted to a fully qualified path to keep `main.rs` under the 800-line monolith guard after the new field plumbing. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Task 5 of CSA-lite Phase 1 fork session. New `run_cmd_caller_fork`
module exposes `resolve_fork_from_caller(config)`, which:
* detects the caller's Claude session via
`csa_session::detect_caller_session()` (env or xurl fallback),
* extracts a token-budgeted conversation prefix via
`csa_acp::PrefixExtractor` when the `acp` feature is on (no-op
`warn!` + None otherwise), respecting `session.fork_prefix_budget`
from the project config, and
* returns a `ForkResolution` carrying the extracted text as
`context_prefix`, with `source_session_id` set to the Claude UUID.
`RunLoopRequest` gains a `caller_fork_resolution` field that
`execute_run_loop` uses as the initial value of `fork_resolution`,
so the existing prepend-to-prompt path (run_cmd_attempt.rs:306-318)
injects the caller's history without a second code path. Genealogy
update on the executed session records the Claude UUID as the fork
source, mirroring the soft-fork shape.
When detection or extraction fails, the resolver returns `None` and
logs a `tracing::warn!`; `handle_run` continues with a normal cold
start. Tests cover: extraction from a valid JSONL fixture
(acp feature), missing-JSONL graceful failure (acp feature),
missing-feature graceful failure (default features), and the
integration path with a fake `CLAUDE_SESSION_ID` pointing at a
non-existent session.
Drive-by: removed a verbose per-path debug log loop in the
legacy-XDG migration block of `main.rs` to keep the file under
the 800-line monolith guard after the new field plumbing; the
aggregate success log on the same match arm still reports the
migrated path count.
Known limitation: failover (post-rate-limit retry) resets
`fork_resolution` to `None`, so subsequent attempts on a fallback
tool lose the caller prefix. This matches existing `--fork-from`
behaviour minus the re-resolution. Re-injection on failover is
Phase 2.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Task 6 of CSA-lite Phase 1: surface Anthropic prompt-cache hit metrics on session result output and JSON payload. Schema - StreamingMetadata (csa-core + csa-acp): add cache_read_input_tokens + cache_hit_ratio() helper. - TokenUsage (csa-session::state): add cache_read_input_tokens with serde(default, skip_serializing_if = Option::is_none) for backwards compatibility, plus cache_hit_ratio() helper. Population - parse_token_usage: recognise "cache_read_input_tokens" before the shorter "input_tokens" probe and add a lookback guard so the longer key cannot shadow input_tokens. - update_cumulative_tokens: only accumulate cache_read when present, so a None response from a non-Claude tool does not zero prior totals. - convert_acp_metadata: bridge the new field across the ACP -> core StreamingMetadata boundary alongside existing input/output_tokens. Display - csa session result: print "Cache read: N tokens (P% hit rate)" line and expose total_token_usage.cache_hit_ratio in JSON payload. - New load_total_token_usage helper reads state.toml directly so cross-project sessions render correctly. Tests - StreamingMetadata cache_hit_ratio: happy path 200K/150K -> 0.75, plus None on missing cache_read, missing input_tokens, and zero input. - parse_token_usage_with_cache_read_input_tokens and the cache_read-only variant verify the lookback guard. Module split - session_cmds_result.rs and csa-acp/src/client.rs grew past the 800-line monolith cap; extracted handle_session_measure into session_cmds_result_measure.rs and the no-verify shell heuristic into csa-acp/src/client/no_verify_detect.rs. No behavior change. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request implements the --fork-from-caller feature, allowing new sessions to be seeded with the conversation history of the invoking Claude session. It includes logic for auto-detecting caller sessions, extracting token-budgeted prefixes from JSONL logs, and adds support for tracking Anthropic prompt caching metrics (cache_read_input_tokens). Feedback identifies a compilation error in the number formatting logic and suggests improving the token estimation heuristic for code-heavy content.
| let len = bytes.len(); | ||
| let mut out = String::with_capacity(len + len / 3); | ||
| for (idx, byte) in bytes.iter().enumerate() { | ||
| if idx > 0 && (len - idx).is_multiple_of(3) { |
There was a problem hiding this comment.
The method is_multiple_of is not part of the Rust standard library for usize or u64. Unless the num-integer crate is imported and the Integer trait is in scope, this will cause a compilation error. It is safer and more idiomatic to use the modulo operator.
Suggested change
| if idx > 0 && (len - idx).is_multiple_of(3) { | |
| if idx > 0 && (len - idx) % 3 == 0 { |
Comment on lines
+197
to
+199
| fn estimate_tokens(content: &str) -> usize { | ||
| content.split_whitespace().count() * 4 / 3 | ||
| } |
There was a problem hiding this comment.
The word-based token estimation heuristic (words * 4 / 3) is significantly inaccurate for code-heavy content, which is a primary use case for this agent. Code often contains many symbols and identifiers that are not separated by whitespace but represent multiple tokens. This could lead to underestimating the token count, potentially causing the extracted prefix to exceed the intended budget or even the model's context limits in extreme cases. Consider using a more conservative heuristic (e.g., character-based) or moving a more robust tokenizer-based estimator to a shared crate like csa-core to avoid duplication while maintaining accuracy.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Implements Phase 1 of CSA-lite mode (#1432): enables CSA child sessions to auto-detect the calling Claude Code agent's session and fork from it, sharing the API-level KV cache prefix. This reduces CSA cold-start cost from ~$3 (cold Opus 200K context) to ~$0.81 (cache-hit Opus) for same-model tasks.
Changes
csa-session/src/caller_detect.rs):detect_caller_session()readsCLAUDE_SESSION_IDenv var, validates session dir, falls back to xurl querycsa-acp/src/prefix_extract.rs):PrefixExtractorreads Claude Code JSONL session files with configurable token budget, skips tool results by defaultsession.fork_prefix_budget(default 32768, range [4096, 131072])--fork-from-callerflag oncsa run(mutually exclusive with--fork-from)cache_read_input_tokenstracking inStreamingMetadata+SessionResultwithcache_hit_ratio()helperAtomic commits
feat(session): add caller session auto-detection for CSA-lite forkfeat(acp): add JSONL prefix extraction for CSA-lite forkfeat(config): add session.fork_prefix_budget for CSA-litefeat(cli): add --fork-from-caller flag for CSA-litefeat(run): wire fork-from-caller into fork resolution pathfeat(metrics): add cache_read_input_tokens tracking for CSA-liteTest plan
just pre-commitpasses (32/32 e2e tests)csa review --check-verdictPASS (codex gpt-5.5)csa run --fork-from-callerwithCLAUDE_SESSION_IDsetCloses #1432 (Phase 1)
🤖 Generated with Claude Code