rafcode 2.1.1 → 2.2.0

package/RAF/ahslfe-config-wizard/plans/04-implement-raf-config-command.md

@@ -0,0 +1,66 @@
+# Task: Implement `raf config` Command
+
+## Objective
+Create the `raf config [prompt]` CLI command that launches an interactive Claude Sonnet TTY session for editing RAF configuration.
+
+## Context
+Users need a natural-language way to modify their config. This command spawns Claude Sonnet with the config documentation as a system prompt, giving it full knowledge of the schema. It also supports `--reset` to restore defaults.
+
+## Dependencies
+01, 02, 03
+
+## Requirements
+
+### `raf config` (no arguments)
+- Spawn an interactive Claude Sonnet TTY session (same node-pty approach used in `raf plan`)
+- Claude receives the config docs from `src/prompts/config-docs.md` as an appended system prompt
+- Claude also receives the current config file contents (or "no config file exists, using defaults")
+- User has a back-and-forth conversation with Claude to modify settings
+- Claude reads, modifies, and writes `~/.raf/raf.config.json`
+- After Claude writes, RAF validates the result and reports errors if invalid
+
+### `raf config <prompt>`
+- Same as above but with an initial prompt pre-filled
+- Still interactive TTY — user can continue the conversation after the initial prompt is handled
+
+### `raf config --reset`
+- Prompt user for confirmation ("This will delete ~/.raf/raf.config.json and restore all defaults. Continue? [y/N]")
+- On confirm: delete the config file, print success message
+- On deny: abort, print "Cancelled"
+
+### Validation after session:
+- When the Claude session ends, read the config file and validate it
+- If invalid: print warnings showing what's wrong, but don't delete the file (user can fix it)
+- If valid: print "Config updated successfully" with a summary of changes
+
+### Model and effort:
+- Use `config.models.config` for the model (default: `'sonnet'`)
+- Use `config.effort.config` for reasoning effort (default: `'medium'`)
+
+## Implementation Steps
+1. Create `src/commands/config.ts` with the Commander.js command definition
+2. Register the command in `src/index.ts` CLI setup
+3. Implement `--reset` flag: confirmation prompt, file deletion, feedback
+4. Build the system prompt: load `src/prompts/config-docs.md` content, append current config state
+5. Spawn interactive Claude session using the existing `ClaudeRunner` TTY infrastructure (same pattern as planning mode)
+6. Pass the model from `config.models.config` and effort from `config.effort.config`
+7. After session ends: validate the config file, report results
+8. Handle edge cases: `~/.raf/` directory doesn't exist (create it), config file doesn't exist yet (that's fine, Claude will create it)
+9. Write tests for the command setup, reset flow, and post-session validation
+
+## Acceptance Criteria
+- [ ] `raf config` starts an interactive Claude Sonnet session with config knowledge
+- [ ] `raf config "use haiku for name generation"` starts session with that prompt
+- [ ] `raf config --reset` prompts for confirmation and deletes config file
+- [ ] Claude session has full config documentation as system prompt
+- [ ] Claude session shows current config state
+- [ ] Post-session validation checks the config file
+- [ ] `~/.raf/` directory is created if it doesn't exist
+- [ ] Command is registered and appears in `raf --help`
+- [ ] Tests cover command setup and reset flow
+
+## Notes
+- Reuse the existing TTY session infrastructure from `src/core/claude-runner.ts` — don't reinvent it
+- The planning command in `src/commands/plan.ts` is the best reference for how to spawn interactive Claude sessions
+- Claude needs `--dangerously-skip-permissions` so it can write to `~/.raf/raf.config.json` without asking
+- The config docs file needs to be readable at runtime — consider how the built JS accesses the .md file (may need to copy it to dist or embed it as a string)

package/RAF/ahslfe-config-wizard/plans/05-update-claude-md.md

@@ -0,0 +1,60 @@
+# Task: Update CLAUDE.md with Config Architecture
+
+## Objective
+Update CLAUDE.md with the new config system architecture, the "configurable by default" principle, and all related documentation.
+
+## Context
+CLAUDE.md serves as the project's internal documentation and instruction set. It needs to reflect the new config system so that future Claude sessions (planning, execution) understand how config works. The user also wants an explicit architectural principle: if a feature can be configurable, it should be configurable via config.
+
+## Dependencies
+01, 02, 03, 04
+
+## Requirements
+
+### Add "Configurable by Default" principle:
+- New architectural decision section stating: if a feature/setting can be configurable, it should be configurable through the config system
+- Default config provides sensible defaults; global config in `~/.raf/raf.config.json` overrides them
+- CLI flags override config values (three-tier precedence: CLI flag > global config > built-in defaults)
+
+### Document the config system:
+- Config file location: `~/.raf/raf.config.json`
+- Schema overview: `models`, `effort`, `timeout`, `maxRetries`, `autoCommit`, `worktree`, `commitFormat`, `claudeCommand`
+- Precedence chain: CLI flag > `~/.raf/raf.config.json` > DEFAULT_CONFIG
+- Validation: strict, unknown keys rejected
+- Reference to `src/types/config.ts` as single source of truth
+
+### Document the `raf config` command:
+- `raf config` — interactive Claude session for config editing
+- `raf config <prompt>` — interactive session with initial prompt
+- `raf config --reset` — restore defaults with confirmation
+- Config docs bundled at `src/prompts/config-docs.md`
+
+### Update existing sections:
+- Update "Development Commands" if any new npm scripts were added
+- Update file structure to include new files (`src/commands/config.ts`, `src/prompts/config-docs.md`)
+- Update any references to the old config system (`raf.config.json` in project dirs → `~/.raf/raf.config.json`)
+- Update the commit format section to reference config templates instead of hardcoded formats
+
+## Implementation Steps
+1. Read current CLAUDE.md to understand existing structure
+2. Add "Configurable by Default" as a new architectural decision section
+3. Add "Configuration System" section documenting schema, loading, validation, precedence
+4. Add `raf config` to the commands documentation
+5. Update directory structure to include new files
+6. Update commit format documentation to reference templates
+7. Update any stale references to the old project-local config
+8. Keep the document concise — link to `src/prompts/config-docs.md` for full config reference rather than duplicating it
+
+## Acceptance Criteria
+- [ ] "Configurable by Default" principle documented as architectural decision
+- [ ] Config system fully documented (location, schema overview, precedence, validation)
+- [ ] `raf config` command documented
+- [ ] Directory structure updated
+- [ ] Old config references updated
+- [ ] Commit format section references templates
+- [ ] CLAUDE.md remains well-organized and concise
+
+## Notes
+- CLAUDE.md is the source of truth for Claude sessions working on this project — accuracy is critical
+- Don't duplicate the full config reference (that's in `src/prompts/config-docs.md`) — just provide an overview and pointer
+- The principle "configurable by default" should guide future development: when adding new features, add corresponding config keys

package/RAF/ahstvo-token-tracker/decisions.md

@@ -0,0 +1,44 @@
+# Project Decisions
+
+## Should short model names (sonnet, haiku, opus) still be supported alongside full model IDs?
+Both supported. Keep short names as aliases and also accept full model IDs like claude-opus-4-5-20251101.
+
+## How should full model IDs be validated?
+Regex pattern. Validate that full IDs match a pattern like claude-{family}-{version} (e.g., claude-opus-4-5-20251101).
+
+## Should default config values stay as short names or change to full model IDs?
+Keep short names. Defaults stay as 'opus', 'sonnet', 'haiku' - simple and auto-resolve to latest.
+
+## How should name generation call Claude CLI to avoid registering a session?
+Use the same spawn-based approach as `raf do` (claude-runner.ts) but without the `--dangerously-skip-permissions` flag. Use `spawn` with `-p` flag for non-interactive print mode. Additionally, use the `--no-session-persistence` flag which prevents sessions from being saved to disk.
+
+## What token usage data is available from Claude CLI?
+Claude CLI provides comprehensive token data in both `--output-format json` and stream-json `result` events:
+- `total_cost_usd`: Total cost in USD (already calculated by Claude CLI)
+- `usage.input_tokens`, `usage.output_tokens`, `usage.cache_creation_input_tokens`, `usage.cache_read_input_tokens`
+- `modelUsage.<model-id>`: Per-model breakdown with `inputTokens`, `outputTokens`, `cacheReadInputTokens`, `cacheCreationInputTokens`, `costUSD`
+- `duration_ms`, `duration_api_ms`: Timing info
+
+## Where should token reports be displayed?
+Console output only. Print token counts and cost estimates to terminal after each task and at the end (total).
+
+## Should pricing be hardcoded or configurable?
+Configurable in raf config, with current prices as defaults.
+
+## Should we use Claude CLI's built-in total_cost_usd or compute our own?
+Compute own price from token counts × configurable prices. CLI's total_cost_usd doesn't work for subscription users.
+
+## How should task execution capture token counts?
+Switch all task execution to stream-json mode (already used in verbose mode). Parse the `result` event for usage data. Non-verbose mode suppresses tool display but still uses stream-json format to capture tokens.
+
+## How should verbose mode toggling during execution work?
+Keypress listener on process.stdin. Since all execution uses stream-json after task 03, toggling is purely a display concern — whether tool-use lines are printed or suppressed. Node's event loop can handle stdin events and child process output concurrently.
+
+## Which key toggles verbose mode?
+Tab key. Press Tab during task execution to toggle verbose display on/off.
+
+## How detailed should the raf config README section be?
+Brief + examples. Command usage, 1-2 basic config examples, mention that `raf config` launches an interactive Claude session for help. Keep it concise like other command sections in the README.
+
+## Should CLAUDE.md mention README update requirements more explicitly?
+Yes. Add a note about always updating README when adding/changing CLI commands, API changes, or important features (like worktrees, config).

package/RAF/ahstvo-token-tracker/input.md

@@ -0,0 +1,3 @@
+- [ ] add token count and report it in the end of each task and total after all tasks finished. bot input and output and add price estimation in $ according to price for opus 4.6 https://claude.com/pricing
+- [ ] run project name generation claude instance not like this " execSync("claude --print ...")" but in a way it will not register session
+- [ ] **Add** **support** **for** **full** **model** **IDs** like claude-opus-4-5-20251101 (in config)

package/RAF/ahstvo-token-tracker/outcomes/01-full-model-id-support.md

@@ -0,0 +1,43 @@
+# Outcome: Support Full Model IDs in Config
+
+## Summary
+
+Added support for full Claude model IDs (e.g., `claude-opus-4-5-20251101`) in the RAF config system, alongside the existing short aliases (`sonnet`, `haiku`, `opus`).
+
+## Changes Made
+
+### `src/types/config.ts`
+- Added `ClaudeModelAlias` type for short names (`sonnet | haiku | opus`)
+- Widened `ClaudeModelName` to accept both short aliases and full model IDs via branded string intersection
+- Added `FULL_MODEL_ID_PATTERN` regex: `/^claude-[a-z]+-\d+(-\d+)*$/`
+- Added `VALID_MODEL_ALIASES` constant (replacing `VALID_MODELS` which is kept as deprecated alias)
+
+### `src/utils/config.ts`
+- Added `isValidModelName()` function that checks against both short aliases and the full model ID regex
+- Updated model validation in `validateConfig()` to use `isValidModelName()`
+- Updated error message to mention both short aliases and full model ID format
+
+### `src/utils/validation.ts`
+- Updated `validateModelName()` to accept full model IDs
+- Updated `resolveModelOption()` return type to `ClaudeModelName`
+- Updated error message to include full model ID example
+- Deprecated `ValidModelName` type alias in favor of `ClaudeModelName`
+
+### `src/prompts/config-docs.md`
+- Updated model value description to mention full model IDs
+- Updated validation rules to describe the new pattern
+- Added "Pinned Model Versions" example config section
+
+### `tests/unit/config.test.ts`
+- Added `isValidModelName` tests: short aliases, full model IDs, and invalid strings
+- Added `validateConfig` tests for full model IDs (with and without date suffix)
+- Added `validateConfig` test for rejecting random strings
+- Added `resolveConfig` test for deep-merging full model ID overrides
+
+## Verification
+
+- TypeScript build passes cleanly
+- All 1066 tests pass (7 new tests added)
+- 2 pre-existing test failures confirmed unrelated (same on base branch)
+
+<promise>COMPLETE</promise>

package/RAF/ahstvo-token-tracker/outcomes/02-name-generation-no-session.md

@@ -0,0 +1,33 @@
+# Outcome: Fix Name Generation to Not Register Sessions
+
+## Summary
+
+Replaced `execSync` with `spawn` in name generation and added `--no-session-persistence` flag to prevent throwaway name generation calls from cluttering the user's Claude session history.
+
+## Changes Made
+
+### `src/utils/name-generator.ts`
+- Replaced `import { execSync }` with `import { spawn }` from `node:child_process`
+- Added `runClaudePrint()` helper function that uses `spawn` with `--no-session-persistence` and `-p` flags
+- Simplified `callSonnetForName()` and `callSonnetForMultipleNames()` to use `runClaudePrint()`
+- Removed `escapeShellArg()` function (no longer needed - spawn passes args as array, not shell string)
+- Removed `escapeShellArg` from exports
+- Kept same 30-second timeout behavior
+- Kept same fallback behavior on failure (returns null for single name, empty array for multiple)
+
+### `tests/unit/name-generator.test.ts`
+- Replaced `execSync` mock with `spawn` mock using EventEmitter-based fake ChildProcess
+- Added `createMockSpawn()` helper to create mock spawn return values
+- Added test for `--no-session-persistence` flag presence
+- Added test for spawn `error` event handling (e.g., ENOENT)
+- Removed `escapeShellArg` tests (function removed)
+- Updated model expectation from `sonnet` to `haiku` (actual default for nameGeneration)
+- All 29 tests pass
+
+## Verification
+
+- TypeScript build passes cleanly
+- All 29 name-generator tests pass
+- Full test suite: 1065 passed, 1 failed (pre-existing, unrelated to this change)
+
+<promise>COMPLETE</promise>

package/RAF/ahstvo-token-tracker/outcomes/03-unify-stream-json-execution.md

@@ -0,0 +1,48 @@
+# Outcome: Unify Task Execution to Stream-JSON Format
+
+## Summary
+
+Unified both `run()` and `runVerbose()` methods in `ClaudeRunner` to use `--output-format stream-json --verbose` internally, enabling token usage data extraction from every task execution. The difference between verbose and non-verbose is now purely a display concern.
+
+## Changes Made
+
+### `src/types/config.ts`
+- Added `ModelTokenUsage` interface (per-model token breakdown)
+- Added `UsageData` interface (aggregate + per-model token usage)
+
+### `src/parsers/stream-renderer.ts`
+- Added `UsageData` and `ModelTokenUsage` imports from types
+- Extended `StreamEvent` interface with `usage` and `modelUsage` fields
+- Added `usageData?: UsageData` field to `RenderResult` interface
+- Updated `renderResult()` to extract usage data from result events
+- Added `extractUsageData()` helper function
+
+### `src/core/claude-runner.ts`
+- Added `UsageData` import from types
+- Added `usageData?: UsageData` field to `RunResult` interface
+- Replaced separate `run()` and `runVerbose()` implementations with a unified `_runStreamJson()` private method
+- `run()` now delegates to `_runStreamJson(prompt, options, false)` — suppresses display
+- `runVerbose()` now delegates to `_runStreamJson(prompt, options, true)` — shows display
+- Both methods now use `--output-format stream-json --verbose` flags
+- Both methods capture `usageData` from the stream-json result event
+
+### `tests/unit/stream-renderer.test.ts`
+- Added 4 new tests for usage data extraction from result events
+- Tests cover: full usage data, missing usage, partial usage, multi-model usage
+
+### `tests/unit/claude-runner.test.ts`
+- Updated test asserting `run()` does NOT have stream-json flags → now asserts it DOES
+- Added trailing newlines to context overflow test data (needed for NDJSON line buffering)
+- Added 4 new tests in "usage data extraction" describe block:
+  - `run()` returns usageData from result events
+  - `runVerbose()` returns usageData from result events
+  - undefined usageData when no result event
+  - `run()` suppresses display but still captures usage data
+
+## Verification
+
+- TypeScript build passes cleanly
+- All 1073 tests pass (8 new tests added)
+- 1 pre-existing test failure confirmed unrelated (same on base branch)
+
+<promise>COMPLETE</promise>

package/RAF/ahstvo-token-tracker/outcomes/04-token-tracking-cost-calculation.md

@@ -0,0 +1,53 @@
+# Outcome: Add Token Tracking and Cost Calculation
+
+## Summary
+
+Implemented token usage accumulation across tasks and cost calculation using configurable per-model pricing. Added pricing config to the RAF config schema, a `TokenTracker` utility class, and model ID to pricing category mapping.
+
+## Changes Made
+
+### `src/types/config.ts`
+- Added `PricingCategory` type (`'opus' | 'sonnet' | 'haiku'`)
+- Added `ModelPricing` interface (inputPerMTok, outputPerMTok, cacheReadPerMTok, cacheCreatePerMTok)
+- Added `PricingConfig` interface (per-category pricing)
+- Added `pricing` field to `RafConfig` interface
+- Added default pricing to `DEFAULT_CONFIG`:
+  - Opus: $15/$75 input/output, $1.50 cache read, $18.75 cache create
+  - Sonnet: $3/$15 input/output, $0.30 cache read, $3.75 cache create
+  - Haiku: $1/$5 input/output, $0.10 cache read, $1.25 cache create
+
+### `src/utils/config.ts`
+- Added `pricing` to `VALID_TOP_LEVEL_KEYS` and validation sets
+- Added pricing validation in `validateConfig()`: validates categories, fields, and values
+- Added pricing deep-merge in `deepMerge()` (per-category field-level merging)
+- Added `resolveModelPricingCategory()`: maps full model IDs (e.g., `claude-opus-4-6`) and short aliases to pricing categories
+- Added `getPricing(category)` and `getPricingConfig()` accessor helpers
+
+### `src/utils/token-tracker.ts` (new file)
+- `TokenTracker` class that accumulates `UsageData` across task executions
+- `addTask(taskId, usage)`: records a task's usage and calculates per-task cost
+- `getTotals()`: returns accumulated usage and cost across all tasks
+- `calculateCost(usage)`: calculates cost using per-model pricing from `modelUsage` breakdown
+- Falls back to sonnet pricing when model breakdown is unavailable or model family is unknown
+- Exports `CostBreakdown` and `TaskUsageEntry` interfaces
+
+### `src/prompts/config-docs.md`
+- Added `pricing` section documenting all fields, defaults, and example override
+- Updated validation rules to mention pricing constraints
+- Updated "Full — All Settings Explicit" example to include pricing
+
+### `tests/unit/token-tracker.test.ts` (new file)
+- 14 tests covering: per-model cost calculation (opus/sonnet/haiku), multi-model usage, cache token pricing, fallback behavior, accumulation across tasks, custom pricing, zero tokens, per-task entries
+
+### `tests/unit/config.test.ts`
+- Added 10 pricing validation tests (valid, partial, invalid types, unknown keys, negative values, Infinity)
+- Added 3 `resolveModelPricingCategory` tests (short aliases, full IDs, unknown families)
+- Added 2 `resolveConfig` pricing tests (defaults, deep-merge partial override)
+
+## Verification
+
+- TypeScript build passes cleanly
+- All 1103 tests pass (15 new tests added)
+- 1 pre-existing test failure confirmed unrelated (same on base branch)
+
+<promise>COMPLETE</promise>

package/RAF/ahstvo-token-tracker/outcomes/05-token-cost-console-reporting.md

@@ -0,0 +1,57 @@
+# Outcome: Add Token/Cost Reporting to Console Output
+
+## Summary
+
+Wired token usage tracking into the `raf do` execution flow, displaying per-task token summaries after each task and a grand total summary after all tasks complete.
+
+## Changes Made
+
+### `src/utils/terminal-symbols.ts`
+- Added `formatNumber()`: formats numbers with thousands separators (e.g., `12,345`)
+- Added `formatCost()`: formats USD cost with 2-4 decimal places (2 for >= $0.01, 4 for smaller)
+- Added `formatTaskTokenSummary()`: per-task summary line showing input/output tokens, cache tokens, estimated cost
+- Added `formatTokenTotalSummary()`: grand total block with dividers, total tokens, cache breakdown, estimated cost
+- Added imports for `UsageData` and `CostBreakdown` types
+
+### `src/commands/do.ts`
+- Imported `TokenTracker`, `formatTaskTokenSummary`, `formatTokenTotalSummary`
+- Instantiated `TokenTracker` at the start of `executeSingleProject()`
+- Added `lastUsageData` variable to capture usage from the last retry attempt
+- After successful tasks: tracks usage and displays per-task summary via `logger.dim()`
+- After failed tasks: tracks partial usage data and displays per-task summary
+- After all tasks: displays grand total summary block if any tasks reported usage
+- Tasks with no usage data (timeout, crash, no result event) are silently skipped
+
+### `CLAUDE.md`
+- Added "Token Usage Tracking" section documenting the feature, key files, and formatting utilities
+
+### `tests/unit/terminal-symbols.test.ts`
+- Added 20 new tests covering:
+  - `formatNumber`: small numbers, thousands separators, large numbers, zero
+  - `formatCost`: zero, normal costs, small costs, threshold boundary
+  - `formatTaskTokenSummary`: no cache, cache read only, cache create only, both caches, small costs
+  - `formatTokenTotalSummary`: no cache, cache read, cache create, both caches, divider lines
+
+## Output Examples
+
+Per-task (displayed in dim text after each task):
+```
+  Tokens: 5,234 in / 1,023 out | Cache: 18,500 read | Est. cost: $0.42
+```
+
+Grand total (displayed after all tasks):
+```
+── Token Usage Summary ──────────────────
+Total tokens: 45,678 in / 12,345 out
+Cache: 125,000 read / 8,000 created
+Estimated cost: $3.75
+─────────────────────────────────────────
+```
+
+## Verification
+
+- TypeScript build passes cleanly
+- All 1122 tests pass (20 new tests added)
+- 1 pre-existing test failure confirmed unrelated (same on base branch)
+
+<promise>COMPLETE</promise>

package/RAF/ahstvo-token-tracker/outcomes/06-runtime-verbose-toggle.md

@@ -0,0 +1,53 @@
+# Outcome: Add Runtime Verbose Toggle During Task Execution
+
+## Summary
+
+Added a runtime verbose toggle that lets users press Tab during task execution to show or hide tool-use activity lines in real-time. The toggle works across sequential tasks, properly handles Ctrl+C for graceful shutdown, and automatically skips setup when stdin is not a TTY.
+
+## Changes Made
+
+### `src/utils/verbose-toggle.ts` (new file)
+- `VerboseToggle` class that manages stdin raw mode and Tab keypress listening
+- `start()`: sets stdin to raw mode, listens for Tab (0x09) to flip verbose state
+- `stop()`: restores stdin to normal mode and removes the listener
+- Ctrl+C (0x03) is re-emitted as `SIGINT` so the shutdown handler still works
+- Shows `[verbose: on]` / `[verbose: off]` indicator on toggle
+- Shows "Press Tab to toggle verbose mode" hint on start
+- No-op when stdin is not a TTY (piped input)
+- Safe to call `start()`/`stop()` multiple times
+
+### `src/core/claude-runner.ts`
+- Added `verboseCheck?: () => boolean` option to `ClaudeRunnerOptions`
+- Updated `_runStreamJson()` to use `verboseCheck` callback when provided, falling back to static `verbose` parameter
+- Both the main stdout handler and the remaining-buffer handler on `close` use `shouldDisplay()` callback
+
+### `src/commands/do.ts`
+- Imported `VerboseToggle`
+- Creates `VerboseToggle` with initial state matching `--verbose` flag
+- Registers `verboseToggle.stop()` as shutdown cleanup callback
+- Starts toggle listener before the task execution loop
+- Passes `verboseCheck: () => verboseToggle.isVerbose` to runner options
+- Stops toggle listener after the task loop completes (before summary output)
+
+### `tests/unit/verbose-toggle.test.ts` (new file)
+- 15 tests covering:
+  - Initial state, active state, TTY/non-TTY behavior
+  - Tab keypress toggling (on/off)
+  - Ctrl+C re-emitting SIGINT
+  - Ignoring non-Tab keypresses
+  - Multiple bytes in single data event
+  - Stop/start lifecycle, double-call safety
+  - No response after stop
+  - Cross-task persistence (stop and restart)
+  - setRawMode error handling
+
+### `tests/unit/claude-runner.test.ts`
+- Added 1 test: `verboseCheck` callback dynamically controls display output
+
+## Verification
+
+- TypeScript build passes cleanly
+- All 1138 tests pass (16 new tests added)
+- 1 pre-existing test failure confirmed unrelated (same on base branch)
+
+<promise>COMPLETE</promise>

package/RAF/ahstvo-token-tracker/outcomes/07-readme-config-docs.md

@@ -0,0 +1,36 @@
+# Outcome: Document raf config in README and Strengthen README Update Policy
+
+## Summary
+
+Added `raf config` documentation to README.md and expanded CLAUDE.md's "Important Reminders" with explicit guidance on when to update the README.
+
+## Changes Made
+
+### `README.md`
+- Added "Configurable" bullet to the Features list
+- Added `### raf config` section after `raf status` in the Commands section, including:
+  - Command usage examples (interactive, with prompt, --reset)
+  - Precedence rule (CLI flags > config file > defaults)
+  - Minimal config file example with 3 common settings (models, worktree, timeout)
+  - Note directing users to the interactive session for full config reference
+- Added `### raf config [prompt]` to the Command Reference section with `--reset` option
+
+### `CLAUDE.md`
+- Expanded "Important Reminders" section with explicit README update policy:
+  - When new CLI commands are added
+  - When existing command flags or behavior change
+  - When important features are added
+  - When the Features list needs updating
+- Separated README and CLAUDE.md update guidance into distinct items
+
+## Verification
+
+- All acceptance criteria met:
+  - README has a `raf config` section with usage and basic example
+  - `raf config` appears in the Command Reference table
+  - Config file location (`~/.raf/raf.config.json`) and precedence rules are mentioned
+  - CLAUDE.md has explicit guidance about when to update README
+  - No existing README content was broken or removed
+  - Documentation tone and style match the rest of the README
+
+<promise>COMPLETE</promise>

package/RAF/ahstvo-token-tracker/plans/01-full-model-id-support.md

@@ -0,0 +1,35 @@
+# Task: Support Full Model IDs in Config
+
+## Objective
+Allow users to specify full model IDs (e.g., `claude-opus-4-5-20251101`) in addition to short aliases (`opus`, `sonnet`, `haiku`) in the RAF config system.
+
+## Context
+Currently, `ClaudeModelName` type only accepts `'sonnet' | 'haiku' | 'opus'`. The Claude CLI `--model` flag already accepts both short aliases and full model IDs, but RAF's config validation rejects full IDs. Users need this to pin specific model versions.
+
+## Requirements
+- Keep short names (`sonnet`, `haiku`, `opus`) working as before — they remain the default
+- Accept full model IDs matching the pattern `claude-{family}-{version}` (e.g., `claude-opus-4-5-20251101`, `claude-sonnet-4-5-20250929`)
+- Validate full model IDs with a regex pattern (not just accept any string)
+- Default config values stay as short names
+- Update all types, validation, config docs, and tests
+
+## Implementation Steps
+1. Widen `ClaudeModelName` type to be a union of the short aliases and a branded/validated string type for full IDs
+2. Add a regex pattern constant for validating full model IDs (e.g., `/^claude-[a-z]+-[\d]+-[\d]+(-\d+)?$/` or similar — examine real model ID formats to get the pattern right)
+3. Update `VALID_MODELS` and the validation logic in `src/utils/config.ts` to accept both short names and full IDs matching the regex
+4. Update `PlanCommandOptions` and `DoCommandOptions` model types to accept full IDs
+5. Update the config documentation in `src/prompts/config-docs.md` to mention full model ID support
+6. Add tests for validation: valid short names, valid full IDs, invalid strings
+
+## Acceptance Criteria
+- [ ] Short model names (`sonnet`, `haiku`, `opus`) continue to work in config
+- [ ] Full model IDs like `claude-opus-4-5-20251101` are accepted in config
+- [ ] Invalid model strings (e.g., `gpt-4`, `random-string`) are rejected with a clear error
+- [ ] Config docs updated to reflect new capabilities
+- [ ] All existing tests pass
+- [ ] New tests cover full model ID validation
+
+## Notes
+- The Claude CLI `--model` flag example from docs: `claude --model claude-sonnet-4-5-20250929`
+- Keep the type system helpful — IDE autocomplete should still suggest short names
+- The regex should be permissive enough to handle future model naming patterns but strict enough to catch obvious typos

package/RAF/ahstvo-token-tracker/plans/02-name-generation-no-session.md

@@ -0,0 +1,36 @@
+# Task: Fix Name Generation to Not Register Sessions
+
+## Objective
+Replace `execSync("claude --print ...")` in name generation with a spawn-based approach using `--no-session-persistence` to prevent sessions from being saved to disk.
+
+## Context
+Project name generation (`src/utils/name-generator.ts`) currently uses `execSync()` to call `claude --model X --print "prompt"`. This registers a session in Claude's session history, cluttering the user's session list with throwaway name generation calls. The `--no-session-persistence` CLI flag prevents this.
+
+## Requirements
+- Replace `execSync` with `spawn` from `child_process` (same approach as `claude-runner.ts`)
+- Use `-p` flag for non-interactive print mode
+- Add `--no-session-persistence` flag to prevent session registration
+- Do NOT use `--dangerously-skip-permissions` (not needed for simple text generation)
+- Keep the same timeout behavior (30 seconds)
+- Keep the same fallback behavior on failure
+- The functions are already `async` so switching to spawn is natural
+
+## Implementation Steps
+1. In `src/utils/name-generator.ts`, replace `execSync` calls in `callSonnetForName()` and `callSonnetForMultipleNames()` with async `spawn`-based execution
+2. Add `--no-session-persistence` to the CLI arguments
+3. Collect stdout from the spawned process and return it as the result
+4. Handle errors and timeouts the same way as before (return null/empty on failure)
+5. Update tests to reflect the new spawn-based approach
+
+## Acceptance Criteria
+- [ ] Name generation no longer uses `execSync`
+- [ ] `--no-session-persistence` flag is passed to Claude CLI
+- [ ] Sessions from name generation do not appear in `claude --resume` picker
+- [ ] Name generation still works correctly (produces valid kebab-case names)
+- [ ] Fallback to generated names works when Claude CLI fails
+- [ ] All existing tests pass
+
+## Notes
+- The `--no-session-persistence` flag is documented in Claude CLI reference: "Disable session persistence so sessions are not saved to disk and cannot be resumed (print mode only)"
+- Consider using a small helper function for spawn-based CLI calls since this pattern could be reused
+- Current `escapeShellArg()` won't be needed with spawn (arguments passed as array, not shell string)

package/RAF/ahstvo-token-tracker/plans/03-unify-stream-json-execution.md

@@ -0,0 +1,44 @@
+# Task: Unify Task Execution to Stream-JSON Format
+
+## Objective
+Switch all task execution modes to use `--output-format stream-json --verbose` so that token usage data is always available from the `result` event.
+
+## Context
+Currently `claude-runner.ts` has two execution methods: `run()` (plain text stdout) and `runVerbose()` (stream-json with tool display). Token usage data is only available in stream-json's `result` event. To enable token tracking, all execution must use stream-json format. The difference between verbose and non-verbose becomes purely a display concern — whether tool descriptions are printed to the console.
+
+## Dependencies
+01
+
+## Requirements
+- All task execution uses `--output-format stream-json --verbose` flags
+- Non-verbose mode still suppresses tool-use display lines but still captures the stream-json data
+- The `result` event from stream-json is always parsed and returned
+- The return type of execution methods is updated to include usage data extracted from the result event
+- Completion detection logic continues to work (parsing text content for markers)
+- No change to interactive mode (`runInteractive()` with node-pty)
+
+## Implementation Steps
+1. Define a `UsageData` interface/type to represent token usage extracted from the stream-json result event (input tokens, output tokens, cache read tokens, cache creation tokens, per-model breakdown)
+2. Update the `run()` method to use stream-json format internally, parse NDJSON lines, extract text content for completion detection, and capture the `result` event
+3. Add a `verbose` display option that controls whether tool-use lines are printed to stdout (true = show tools, false = suppress)
+4. Extract usage data from the `result` event's `usage` and `modelUsage` fields
+5. Update the return type of both `run()` and `runVerbose()` (or unified method) to include `UsageData`
+6. Update callers in `src/commands/do.ts` to receive and pass through usage data
+7. Update tests for the new execution flow
+
+## Acceptance Criteria
+- [ ] `run()` and `runVerbose()` both return token usage data
+- [ ] Non-verbose execution suppresses tool display but still gets usage data
+- [ ] Verbose execution shows tool display as before AND returns usage data
+- [ ] Completion detection (COMPLETE/FAILED markers) still works
+- [ ] Context overflow detection still works
+- [ ] Timeout behavior unchanged
+- [ ] All existing tests pass
+
+## Notes
+- The stream-json result event structure (from actual CLI output):
+  ```
+  {"type":"result","usage":{"input_tokens":N,"output_tokens":N,"cache_creation_input_tokens":N,"cache_read_input_tokens":N},"modelUsage":{"claude-opus-4-6":{"inputTokens":N,"outputTokens":N,...}}}
+  ```
+- Consider merging `run()` and `runVerbose()` into a single method with a `verbose` option to reduce code duplication
+- The `renderStreamEvent()` function in `src/parsers/stream-renderer.ts` already handles parsing — extend it to also return usage data when a `result` event is encountered