rafcode 2.3.0 → 2.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (109) hide show
  1. package/CLAUDE.md +19 -4
  2. package/RAF/ahvrih-rate-forge/decisions.md +70 -0
  3. package/RAF/ahvrih-rate-forge/input.md +44 -0
  4. package/RAF/ahvrih-rate-forge/outcomes/01-remove-claude-command-config.md +58 -0
  5. package/RAF/ahvrih-rate-forge/outcomes/02-fix-mixed-attempt-cost.md +46 -0
  6. package/RAF/ahvrih-rate-forge/outcomes/03-rate-limit-estimation.md +82 -0
  7. package/RAF/ahvrih-rate-forge/outcomes/04-show-version-in-do-logs.md +45 -0
  8. package/RAF/ahvrih-rate-forge/outcomes/05-sync-main-before-worktree.md +96 -0
  9. package/RAF/ahvrih-rate-forge/outcomes/06-sync-readme-with-codebase.md +45 -0
  10. package/RAF/ahvrih-rate-forge/outcomes/07-no-session-persistence.md +26 -0
  11. package/RAF/ahvrih-rate-forge/outcomes/08-plan-execution-metadata.md +130 -0
  12. package/RAF/ahvrih-rate-forge/plans/01-remove-claude-command-config.md +36 -0
  13. package/RAF/ahvrih-rate-forge/plans/02-fix-mixed-attempt-cost.md +33 -0
  14. package/RAF/ahvrih-rate-forge/plans/03-rate-limit-estimation.md +82 -0
  15. package/RAF/ahvrih-rate-forge/plans/04-show-version-in-do-logs.md +32 -0
  16. package/RAF/ahvrih-rate-forge/plans/05-sync-main-before-worktree.md +40 -0
  17. package/RAF/ahvrih-rate-forge/plans/06-sync-readme-with-codebase.md +61 -0
  18. package/RAF/ahvrih-rate-forge/plans/07-no-session-persistence.md +28 -0
  19. package/RAF/ahvrih-rate-forge/plans/08-plan-execution-metadata.md +123 -0
  20. package/README.md +27 -7
  21. package/dist/commands/config.d.ts.map +1 -1
  22. package/dist/commands/config.js +1 -6
  23. package/dist/commands/config.js.map +1 -1
  24. package/dist/commands/do.d.ts.map +1 -1
  25. package/dist/commands/do.js +106 -18
  26. package/dist/commands/do.js.map +1 -1
  27. package/dist/commands/plan.d.ts.map +1 -1
  28. package/dist/commands/plan.js +77 -2
  29. package/dist/commands/plan.js.map +1 -1
  30. package/dist/core/claude-runner.d.ts +6 -6
  31. package/dist/core/claude-runner.d.ts.map +1 -1
  32. package/dist/core/claude-runner.js +9 -10
  33. package/dist/core/claude-runner.js.map +1 -1
  34. package/dist/core/failure-analyzer.d.ts.map +1 -1
  35. package/dist/core/failure-analyzer.js +3 -3
  36. package/dist/core/failure-analyzer.js.map +1 -1
  37. package/dist/core/pull-request.js +3 -3
  38. package/dist/core/pull-request.js.map +1 -1
  39. package/dist/core/state-derivation.d.ts +5 -0
  40. package/dist/core/state-derivation.d.ts.map +1 -1
  41. package/dist/core/state-derivation.js +14 -4
  42. package/dist/core/state-derivation.js.map +1 -1
  43. package/dist/core/worktree.d.ts +32 -0
  44. package/dist/core/worktree.d.ts.map +1 -1
  45. package/dist/core/worktree.js +215 -0
  46. package/dist/core/worktree.js.map +1 -1
  47. package/dist/prompts/amend.d.ts.map +1 -1
  48. package/dist/prompts/amend.js +26 -11
  49. package/dist/prompts/amend.js.map +1 -1
  50. package/dist/prompts/planning.d.ts.map +1 -1
  51. package/dist/prompts/planning.js +26 -11
  52. package/dist/prompts/planning.js.map +1 -1
  53. package/dist/types/config.d.ts +30 -13
  54. package/dist/types/config.d.ts.map +1 -1
  55. package/dist/types/config.js +14 -10
  56. package/dist/types/config.js.map +1 -1
  57. package/dist/utils/config.d.ts +47 -4
  58. package/dist/utils/config.d.ts.map +1 -1
  59. package/dist/utils/config.js +176 -30
  60. package/dist/utils/config.js.map +1 -1
  61. package/dist/utils/frontmatter.d.ts +43 -0
  62. package/dist/utils/frontmatter.d.ts.map +1 -0
  63. package/dist/utils/frontmatter.js +85 -0
  64. package/dist/utils/frontmatter.js.map +1 -0
  65. package/dist/utils/name-generator.d.ts.map +1 -1
  66. package/dist/utils/name-generator.js +2 -3
  67. package/dist/utils/name-generator.js.map +1 -1
  68. package/dist/utils/session-parser.d.ts +44 -0
  69. package/dist/utils/session-parser.d.ts.map +1 -0
  70. package/dist/utils/session-parser.js +122 -0
  71. package/dist/utils/session-parser.js.map +1 -0
  72. package/dist/utils/terminal-symbols.d.ts +22 -3
  73. package/dist/utils/terminal-symbols.d.ts.map +1 -1
  74. package/dist/utils/terminal-symbols.js +52 -18
  75. package/dist/utils/terminal-symbols.js.map +1 -1
  76. package/dist/utils/token-tracker.d.ts +20 -0
  77. package/dist/utils/token-tracker.d.ts.map +1 -1
  78. package/dist/utils/token-tracker.js +57 -2
  79. package/dist/utils/token-tracker.js.map +1 -1
  80. package/package.json +1 -1
  81. package/src/commands/config.ts +0 -7
  82. package/src/commands/do.ts +141 -20
  83. package/src/commands/plan.ts +87 -1
  84. package/src/core/claude-runner.ts +16 -17
  85. package/src/core/failure-analyzer.ts +3 -3
  86. package/src/core/pull-request.ts +3 -3
  87. package/src/core/state-derivation.ts +20 -4
  88. package/src/core/worktree.ts +230 -0
  89. package/src/prompts/amend.ts +26 -11
  90. package/src/prompts/config-docs.md +91 -29
  91. package/src/prompts/planning.ts +26 -11
  92. package/src/types/config.ts +46 -21
  93. package/src/utils/config.ts +200 -33
  94. package/src/utils/frontmatter.ts +110 -0
  95. package/src/utils/name-generator.ts +2 -3
  96. package/src/utils/session-parser.ts +161 -0
  97. package/src/utils/terminal-symbols.ts +68 -16
  98. package/src/utils/token-tracker.ts +65 -2
  99. package/tests/unit/claude-runner-interactive.test.ts +8 -6
  100. package/tests/unit/claude-runner.test.ts +5 -66
  101. package/tests/unit/config-command.test.ts +6 -6
  102. package/tests/unit/config.test.ts +268 -45
  103. package/tests/unit/frontmatter.test.ts +182 -0
  104. package/tests/unit/post-execution-picker.test.ts +5 -0
  105. package/tests/unit/session-parser.test.ts +301 -0
  106. package/tests/unit/terminal-symbols.test.ts +142 -0
  107. package/tests/unit/token-tracker.test.ts +304 -1
  108. package/tests/unit/validation.test.ts +6 -4
  109. package/tests/unit/worktree.test.ts +242 -0
@@ -0,0 +1,161 @@
1
+ /**
2
+ * Utilities for parsing Claude CLI session files to extract token usage data.
3
+ * Claude CLI saves session data to ~/.claude/projects/<escaped-path>/<session-id>.jsonl
4
+ */
5
+
6
+ import * as fs from 'node:fs';
7
+ import * as path from 'node:path';
8
+ import * as os from 'node:os';
9
+ import type { UsageData } from '../types/config.js';
10
+
11
+ /** Raw usage structure from Claude session JSONL assistant message entries. */
12
+ interface SessionMessageUsage {
13
+ input_tokens?: number;
14
+ output_tokens?: number;
15
+ cache_read_input_tokens?: number;
16
+ cache_creation_input_tokens?: number;
17
+ }
18
+
19
+ /** Structure of an assistant message entry in the session JSONL. */
20
+ interface SessionMessageEntry {
21
+ type: 'assistant';
22
+ message?: {
23
+ usage?: SessionMessageUsage;
24
+ model?: string;
25
+ };
26
+ costUSD?: number;
27
+ }
28
+
29
+ /** Result of parsing a session file. */
30
+ export interface SessionParseResult {
31
+ /** Accumulated usage data from all assistant messages. */
32
+ usage: UsageData;
33
+ /** Whether parsing was successful. */
34
+ success: boolean;
35
+ /** Error message if parsing failed. */
36
+ error?: string;
37
+ }
38
+
39
+ /**
40
+ * Escape a path for use in Claude's project directory naming scheme.
41
+ * Claude escapes `/` to `-` in project paths.
42
+ */
43
+ export function escapeProjectPath(projectPath: string): string {
44
+ // Remove leading slash and replace remaining slashes with dashes
45
+ return projectPath.replace(/^\//, '').replace(/\//g, '-');
46
+ }
47
+
48
+ /**
49
+ * Compute the expected session file path for a given session ID and working directory.
50
+ *
51
+ * @param sessionId - The UUID session ID passed to --session-id
52
+ * @param cwd - The working directory where Claude was run (project path)
53
+ * @returns The expected path to the session JSONL file
54
+ */
55
+ export function getSessionFilePath(sessionId: string, cwd: string): string {
56
+ const claudeDir = path.join(os.homedir(), '.claude', 'projects');
57
+ const escapedPath = escapeProjectPath(cwd);
58
+ return path.join(claudeDir, escapedPath, `${sessionId}.jsonl`);
59
+ }
60
+
61
+ /**
62
+ * Parse a Claude session JSONL file and extract accumulated token usage data.
63
+ *
64
+ * @param sessionFilePath - Path to the session JSONL file
65
+ * @returns Parsed usage data or error information
66
+ */
67
+ export function parseSessionFile(sessionFilePath: string): SessionParseResult {
68
+ const emptyUsage: UsageData = {
69
+ inputTokens: 0,
70
+ outputTokens: 0,
71
+ cacheReadInputTokens: 0,
72
+ cacheCreationInputTokens: 0,
73
+ modelUsage: {},
74
+ };
75
+
76
+ if (!fs.existsSync(sessionFilePath)) {
77
+ return {
78
+ usage: emptyUsage,
79
+ success: false,
80
+ error: `Session file not found: ${sessionFilePath}`,
81
+ };
82
+ }
83
+
84
+ try {
85
+ const content = fs.readFileSync(sessionFilePath, 'utf-8');
86
+ const lines = content.trim().split('\n').filter(line => line.trim());
87
+
88
+ const accumulated: UsageData = { ...emptyUsage, modelUsage: {} };
89
+
90
+ for (const line of lines) {
91
+ try {
92
+ const entry = JSON.parse(line) as Record<string, unknown>;
93
+
94
+ // Only process assistant message entries
95
+ if (entry.type !== 'assistant') continue;
96
+
97
+ const assistantEntry = entry as unknown as SessionMessageEntry;
98
+ const usage = assistantEntry.message?.usage;
99
+ const model = assistantEntry.message?.model;
100
+
101
+ if (!usage) continue;
102
+
103
+ const inputTokens = usage.input_tokens ?? 0;
104
+ const outputTokens = usage.output_tokens ?? 0;
105
+ const cacheReadTokens = usage.cache_read_input_tokens ?? 0;
106
+ const cacheCreateTokens = usage.cache_creation_input_tokens ?? 0;
107
+
108
+ // Accumulate aggregate totals
109
+ accumulated.inputTokens += inputTokens;
110
+ accumulated.outputTokens += outputTokens;
111
+ accumulated.cacheReadInputTokens += cacheReadTokens;
112
+ accumulated.cacheCreationInputTokens += cacheCreateTokens;
113
+
114
+ // Accumulate per-model usage
115
+ if (model) {
116
+ const existing = accumulated.modelUsage[model];
117
+ if (existing) {
118
+ existing.inputTokens += inputTokens;
119
+ existing.outputTokens += outputTokens;
120
+ existing.cacheReadInputTokens += cacheReadTokens;
121
+ existing.cacheCreationInputTokens += cacheCreateTokens;
122
+ } else {
123
+ accumulated.modelUsage[model] = {
124
+ inputTokens,
125
+ outputTokens,
126
+ cacheReadInputTokens: cacheReadTokens,
127
+ cacheCreationInputTokens: cacheCreateTokens,
128
+ };
129
+ }
130
+ }
131
+ } catch {
132
+ // Skip malformed lines
133
+ continue;
134
+ }
135
+ }
136
+
137
+ return {
138
+ usage: accumulated,
139
+ success: true,
140
+ };
141
+ } catch (error) {
142
+ return {
143
+ usage: emptyUsage,
144
+ success: false,
145
+ error: `Failed to parse session file: ${error}`,
146
+ };
147
+ }
148
+ }
149
+
150
+ /**
151
+ * Parse a Claude session by session ID and working directory.
152
+ * Convenience wrapper around getSessionFilePath + parseSessionFile.
153
+ *
154
+ * @param sessionId - The UUID session ID passed to --session-id
155
+ * @param cwd - The working directory where Claude was run
156
+ * @returns Parsed usage data or error information
157
+ */
158
+ export function parseSessionById(sessionId: string, cwd: string): SessionParseResult {
159
+ const filePath = getSessionFilePath(sessionId, cwd);
160
+ return parseSessionFile(filePath);
161
+ }
@@ -7,6 +7,16 @@ import { formatElapsedTime } from './timer.js';
7
7
  import type { UsageData } from '../types/config.js';
8
8
  import type { CostBreakdown, TaskUsageEntry } from './token-tracker.js';
9
9
 
10
+ /** Options for token summary formatting. */
11
+ export interface TokenSummaryOptions {
12
+ /** Whether to show cache token counts. Default: true */
13
+ showCacheTokens?: boolean;
14
+ /** Whether to show rate limit percentage. Default: true */
15
+ showRateLimitEstimate?: boolean;
16
+ /** Rate limit percentage to display (requires showRateLimitEstimate: true) */
17
+ rateLimitPercentage?: number;
18
+ }
19
+
10
20
  /**
11
21
  * Visual symbols for terminal output using dots/symbols style.
12
22
  */
@@ -145,6 +155,17 @@ export function formatCost(cost: number): string {
145
155
  return `$${cost.toFixed(2)}`;
146
156
  }
147
157
 
158
+ /**
159
+ * Formats a rate limit percentage for display.
160
+ * Uses tilde (~) prefix to indicate estimate.
161
+ */
162
+ export function formatRateLimitPercentage(percentage: number): string {
163
+ if (percentage === 0) return '~0% of 5h window';
164
+ if (percentage < 0.1) return `~${percentage.toFixed(2)}% of 5h window`;
165
+ if (percentage < 1) return `~${percentage.toFixed(1)}% of 5h window`;
166
+ return `~${Math.round(percentage)}% of 5h window`;
167
+ }
168
+
148
169
  /**
149
170
  * Formats a single line of token usage (for a single attempt or total).
150
171
  * Used internally by formatTaskTokenSummary.
@@ -153,67 +174,94 @@ function formatTokenLine(
153
174
  usage: UsageData,
154
175
  costValue: number,
155
176
  prefix: string = '',
156
- indent: string = ' '
177
+ indent: string = ' ',
178
+ options: TokenSummaryOptions = {}
157
179
  ): string {
180
+ const { showCacheTokens = true, showRateLimitEstimate = false, rateLimitPercentage } = options;
158
181
  const parts: string[] = [];
159
182
  const tokenPart = `${formatNumber(usage.inputTokens)} in / ${formatNumber(usage.outputTokens)} out`;
160
183
  parts.push(prefix ? `${prefix}: ${tokenPart}` : `Tokens: ${tokenPart}`);
161
184
 
162
- const cacheTotal = usage.cacheReadInputTokens + usage.cacheCreationInputTokens;
163
- if (cacheTotal > 0) {
164
- if (usage.cacheReadInputTokens > 0 && usage.cacheCreationInputTokens > 0) {
165
- parts.push(`Cache: ${formatNumber(usage.cacheReadInputTokens)} read / ${formatNumber(usage.cacheCreationInputTokens)} created`);
166
- } else if (usage.cacheReadInputTokens > 0) {
167
- parts.push(`Cache: ${formatNumber(usage.cacheReadInputTokens)} read`);
168
- } else {
169
- parts.push(`Cache: ${formatNumber(usage.cacheCreationInputTokens)} created`);
185
+ if (showCacheTokens) {
186
+ const cacheTotal = usage.cacheReadInputTokens + usage.cacheCreationInputTokens;
187
+ if (cacheTotal > 0) {
188
+ if (usage.cacheReadInputTokens > 0 && usage.cacheCreationInputTokens > 0) {
189
+ parts.push(`Cache: ${formatNumber(usage.cacheReadInputTokens)} read / ${formatNumber(usage.cacheCreationInputTokens)} created`);
190
+ } else if (usage.cacheReadInputTokens > 0) {
191
+ parts.push(`Cache: ${formatNumber(usage.cacheReadInputTokens)} read`);
192
+ } else {
193
+ parts.push(`Cache: ${formatNumber(usage.cacheCreationInputTokens)} created`);
194
+ }
170
195
  }
171
196
  }
172
197
 
173
198
  parts.push(`Est. cost: ${formatCost(costValue)}`);
199
+
200
+ if (showRateLimitEstimate && rateLimitPercentage !== undefined) {
201
+ parts.push(formatRateLimitPercentage(rateLimitPercentage));
202
+ }
203
+
174
204
  return `${indent}${parts.join(' | ')}`;
175
205
  }
176
206
 
177
207
  /**
178
208
  * Formats a per-task token usage summary.
179
- * For single-attempt tasks: " Tokens: 5,234 in / 1,023 out | Cache: 18,500 read | Est. cost: $0.42"
209
+ * For single-attempt tasks: " Tokens: 5,234 in / 1,023 out | Cache: 18,500 read | Est. cost: $0.42 | ~2% of 5h window"
180
210
  * For multi-attempt tasks: shows per-attempt breakdown plus total.
181
211
  *
182
212
  * @param entry - The TaskUsageEntry containing accumulated usage, cost, and attempts array
183
213
  * @param calculateAttemptCost - Optional function to calculate cost for a single attempt's UsageData
214
+ * @param options - Display options for showing cache tokens and rate limit percentage
184
215
  */
185
216
  export function formatTaskTokenSummary(
186
217
  entry: TaskUsageEntry,
187
- calculateAttemptCost?: (usage: UsageData) => CostBreakdown
218
+ calculateAttemptCost?: (usage: UsageData) => CostBreakdown,
219
+ options: TokenSummaryOptions = {}
188
220
  ): string {
189
221
  // Single-attempt: render exactly as before (no per-attempt breakdown)
190
222
  if (entry.attempts.length <= 1) {
191
- return formatTokenLine(entry.usage, entry.cost.totalCost);
223
+ return formatTokenLine(entry.usage, entry.cost.totalCost, '', ' ', options);
192
224
  }
193
225
 
194
226
  // Multi-attempt: show per-attempt lines plus total
227
+ // Per-attempt lines don't show rate limit (only show on total)
228
+ const perAttemptOptions: TokenSummaryOptions = {
229
+ ...options,
230
+ showRateLimitEstimate: false,
231
+ rateLimitPercentage: undefined,
232
+ };
233
+
195
234
  const lines: string[] = [];
196
235
  entry.attempts.forEach((attemptUsage, i) => {
197
236
  const attemptCost = calculateAttemptCost
198
237
  ? calculateAttemptCost(attemptUsage).totalCost
199
238
  : 0;
200
- lines.push(formatTokenLine(attemptUsage, attemptCost, `Attempt ${i + 1}`, ' '));
239
+ lines.push(formatTokenLine(attemptUsage, attemptCost, `Attempt ${i + 1}`, ' ', perAttemptOptions));
201
240
  });
202
- lines.push(formatTokenLine(entry.usage, entry.cost.totalCost, 'Total', ' '));
241
+ lines.push(formatTokenLine(entry.usage, entry.cost.totalCost, 'Total', ' ', options));
203
242
  return lines.join('\n');
204
243
  }
205
244
 
206
245
  /**
207
246
  * Formats the grand total token usage summary block.
208
247
  * Displayed after all tasks complete.
248
+ *
249
+ * @param usage - Total usage data
250
+ * @param cost - Total cost breakdown
251
+ * @param options - Display options for cache tokens and rate limit
209
252
  */
210
- export function formatTokenTotalSummary(usage: UsageData, cost: CostBreakdown): string {
253
+ export function formatTokenTotalSummary(
254
+ usage: UsageData,
255
+ cost: CostBreakdown,
256
+ options: TokenSummaryOptions = {}
257
+ ): string {
258
+ const { showCacheTokens = true, showRateLimitEstimate = false, rateLimitPercentage } = options;
211
259
  const lines: string[] = [];
212
260
  const divider = '── Token Usage Summary ──────────────────';
213
261
  lines.push(divider);
214
262
  lines.push(`Total tokens: ${formatNumber(usage.inputTokens)} in / ${formatNumber(usage.outputTokens)} out`);
215
263
 
216
- if (usage.cacheReadInputTokens > 0 || usage.cacheCreationInputTokens > 0) {
264
+ if (showCacheTokens && (usage.cacheReadInputTokens > 0 || usage.cacheCreationInputTokens > 0)) {
217
265
  const cacheParts: string[] = [];
218
266
  if (usage.cacheReadInputTokens > 0) {
219
267
  cacheParts.push(`${formatNumber(usage.cacheReadInputTokens)} read`);
@@ -225,6 +273,10 @@ export function formatTokenTotalSummary(usage: UsageData, cost: CostBreakdown):
225
273
  }
226
274
 
227
275
  lines.push(`Estimated cost: ${formatCost(cost.totalCost)}`);
276
+
277
+ if (showRateLimitEstimate && rateLimitPercentage !== undefined) {
278
+ lines.push(formatRateLimitPercentage(rateLimitPercentage));
279
+ }
228
280
  lines.push('─────────────────────────────────────────');
229
281
  return lines.join('\n');
230
282
  }
@@ -1,5 +1,5 @@
1
1
  import { UsageData, PricingConfig } from '../types/config.js';
2
- import { resolveModelPricingCategory, getPricingConfig } from './config.js';
2
+ import { resolveModelPricingCategory, getPricingConfig, getRateLimitWindowConfig } from './config.js';
3
3
 
4
4
  /** Cost breakdown for a single task or accumulated total. */
5
5
  export interface CostBreakdown {
@@ -21,6 +21,29 @@ export interface TaskUsageEntry {
21
21
  attempts: UsageData[];
22
22
  }
23
23
 
24
+ /**
25
+ * Sum multiple CostBreakdown objects into a single total.
26
+ */
27
+ export function sumCostBreakdowns(costs: CostBreakdown[]): CostBreakdown {
28
+ const result: CostBreakdown = {
29
+ inputCost: 0,
30
+ outputCost: 0,
31
+ cacheReadCost: 0,
32
+ cacheCreateCost: 0,
33
+ totalCost: 0,
34
+ };
35
+
36
+ for (const cost of costs) {
37
+ result.inputCost += cost.inputCost;
38
+ result.outputCost += cost.outputCost;
39
+ result.cacheReadCost += cost.cacheReadCost;
40
+ result.cacheCreateCost += cost.cacheCreateCost;
41
+ result.totalCost += cost.totalCost;
42
+ }
43
+
44
+ return result;
45
+ }
46
+
24
47
  /**
25
48
  * Merge multiple UsageData objects into a single accumulated UsageData.
26
49
  * Sums all token fields and merges modelUsage maps.
@@ -72,10 +95,15 @@ export class TokenTracker {
72
95
  /**
73
96
  * Record usage data from a completed task.
74
97
  * Accepts an array of UsageData (one per attempt) and accumulates them.
98
+ * Cost is calculated per-attempt to avoid underreporting when some attempts
99
+ * have modelUsage and others only have aggregate fields.
75
100
  */
76
101
  addTask(taskId: string, attempts: UsageData[]): TaskUsageEntry {
77
102
  const usage = accumulateUsage(attempts);
78
- const cost = this.calculateCost(usage);
103
+ // Calculate cost per-attempt, then sum. This ensures attempts with only
104
+ // aggregate fields use sonnet fallback pricing independently.
105
+ const perAttemptCosts = attempts.map((attempt) => this.calculateCost(attempt));
106
+ const cost = sumCostBreakdowns(perAttemptCosts);
79
107
  const entry: TaskUsageEntry = { taskId, usage, cost, attempts };
80
108
  this.entries.push(entry);
81
109
  return entry;
@@ -174,4 +202,39 @@ export class TokenTracker {
174
202
  result.totalCost = result.inputCost + result.outputCost + result.cacheReadCost + result.cacheCreateCost;
175
203
  return result;
176
204
  }
205
+
206
+ /**
207
+ * Calculate the 5h rate limit window percentage for a given cost.
208
+ * Converts cost to Sonnet-equivalent tokens using the configured Sonnet pricing,
209
+ * then divides by the configured cap.
210
+ *
211
+ * @param totalCost - The total cost in dollars
212
+ * @param sonnetTokenCap - Optional override for the Sonnet-equivalent token cap (defaults to config value)
213
+ * @returns The percentage of the 5h window consumed (0-100+)
214
+ */
215
+ calculateRateLimitPercentage(totalCost: number, sonnetTokenCap?: number): number {
216
+ if (totalCost === 0) return 0;
217
+
218
+ // Get the configured cap or use the provided override
219
+ const cap = sonnetTokenCap ?? getRateLimitWindowConfig().sonnetTokenCap;
220
+
221
+ // Calculate the average Sonnet cost per token
222
+ // Using the average of input and output pricing (simplified approach)
223
+ const sonnetPricing = this.pricingConfig.sonnet;
224
+ const avgSonnetCostPerToken = (sonnetPricing.inputPerMTok + sonnetPricing.outputPerMTok) / 2 / 1_000_000;
225
+
226
+ // Convert cost to Sonnet-equivalent tokens
227
+ const sonnetEquivalentTokens = totalCost / avgSonnetCostPerToken;
228
+
229
+ // Calculate percentage
230
+ return (sonnetEquivalentTokens / cap) * 100;
231
+ }
232
+
233
+ /**
234
+ * Get the cumulative 5h window percentage across all recorded tasks.
235
+ */
236
+ getCumulativeRateLimitPercentage(sonnetTokenCap?: number): number {
237
+ const totals = this.getTotals();
238
+ return this.calculateRateLimitPercentage(totals.cost.totalCost, sonnetTokenCap);
239
+ }
177
240
  }
@@ -144,7 +144,9 @@ describe('ClaudeRunner - runInteractive', () => {
144
144
 
145
145
  const spawnArgs = mockPtySpawn.mock.calls[0][1] as string[];
146
146
  expect(spawnArgs).toContain('--model');
147
- expect(spawnArgs).toContain('opus');
147
+ // Default model comes from config, could be short alias or full model ID
148
+ const modelArgIndex = spawnArgs.indexOf('--model');
149
+ expect(spawnArgs[modelArgIndex + 1]).toMatch(/^(opus|sonnet|haiku|claude-(opus|sonnet|haiku)-.+)$/);
148
150
 
149
151
  mockProc._exitCallback({ exitCode: 0 });
150
152
  await runPromise;
@@ -244,8 +246,8 @@ describe('ClaudeRunner - runInteractive', () => {
244
246
  });
245
247
  });
246
248
 
247
- describe('effort level (not applied in interactive mode)', () => {
248
- it('should NOT set CLAUDE_CODE_EFFORT_LEVEL in runInteractive env', async () => {
249
+ describe('environment passing', () => {
250
+ it('should pass process.env to pty spawn in runInteractive', async () => {
249
251
  const mockProc = createMockPtyProcess();
250
252
  const mockStdin = createMockStdin();
251
253
  const mockStdout = createMockStdout();
@@ -256,12 +258,12 @@ describe('ClaudeRunner - runInteractive', () => {
256
258
  mockPtySpawn.mockReturnValue(mockProc);
257
259
 
258
260
  const runner = new ClaudeRunner();
259
- // Even if effortLevel were somehow passed, interactive mode should use process.env as-is
260
261
  const runPromise = runner.runInteractive('system', 'user');
261
262
 
262
263
  const spawnOptions = mockPtySpawn.mock.calls[0][2];
263
- // Interactive mode passes process.env directly, no effort level override
264
- expect(spawnOptions.env).not.toHaveProperty('CLAUDE_CODE_EFFORT_LEVEL');
264
+ // Interactive mode passes process.env directly
265
+ // Note: effortLevel option was removed from ClaudeRunner in favor of per-task model resolution
266
+ expect(spawnOptions.env).toBeDefined();
265
267
 
266
268
  mockProc._exitCallback({ exitCode: 0 });
267
269
  await runPromise;
@@ -473,7 +473,9 @@ describe('ClaudeRunner', () => {
473
473
  });
474
474
  });
475
475
 
476
- describe('effort level', () => {
476
+ // Note: effortLevel option was removed from ClaudeRunner in favor of per-task model resolution
477
+ // via plan frontmatter. See effortMapping config and frontmatter.ts for the new approach.
478
+ describe('environment handling', () => {
477
479
  function createMockProcess() {
478
480
  const stdout = new EventEmitter();
479
481
  const stderr = new EventEmitter();
@@ -484,35 +486,7 @@ describe('ClaudeRunner', () => {
484
486
  return proc;
485
487
  }
486
488
 
487
- it('should set CLAUDE_CODE_EFFORT_LEVEL env var in run() when effortLevel is provided', async () => {
488
- const mockProc = createMockProcess();
489
- mockSpawn.mockReturnValue(mockProc);
490
-
491
- const runner = new ClaudeRunner();
492
- const runPromise = runner.run('test prompt', { timeout: 60, effortLevel: 'medium' });
493
-
494
- mockProc.emit('close', 0);
495
- await runPromise;
496
-
497
- const spawnOptions = mockSpawn.mock.calls[0][2];
498
- expect(spawnOptions.env.CLAUDE_CODE_EFFORT_LEVEL).toBe('medium');
499
- });
500
-
501
- it('should set CLAUDE_CODE_EFFORT_LEVEL env var in runVerbose() when effortLevel is provided', async () => {
502
- const mockProc = createMockProcess();
503
- mockSpawn.mockReturnValue(mockProc);
504
-
505
- const runner = new ClaudeRunner();
506
- const runPromise = runner.runVerbose('test prompt', { timeout: 60, effortLevel: 'medium' });
507
-
508
- mockProc.emit('close', 0);
509
- await runPromise;
510
-
511
- const spawnOptions = mockSpawn.mock.calls[0][2];
512
- expect(spawnOptions.env.CLAUDE_CODE_EFFORT_LEVEL).toBe('medium');
513
- });
514
-
515
- it('should NOT set CLAUDE_CODE_EFFORT_LEVEL when effortLevel is not provided in run()', async () => {
489
+ it('should pass process.env to child process in run()', async () => {
516
490
  const mockProc = createMockProcess();
517
491
  mockSpawn.mockReturnValue(mockProc);
518
492
 
@@ -523,11 +497,10 @@ describe('ClaudeRunner', () => {
523
497
  await runPromise;
524
498
 
525
499
  const spawnOptions = mockSpawn.mock.calls[0][2];
526
- // env should be process.env directly (no CLAUDE_CODE_EFFORT_LEVEL override)
527
500
  expect(spawnOptions.env).toBe(process.env);
528
501
  });
529
502
 
530
- it('should NOT set CLAUDE_CODE_EFFORT_LEVEL when effortLevel is not provided in runVerbose()', async () => {
503
+ it('should pass process.env to child process in runVerbose()', async () => {
531
504
  const mockProc = createMockProcess();
532
505
  mockSpawn.mockReturnValue(mockProc);
533
506
 
@@ -538,42 +511,8 @@ describe('ClaudeRunner', () => {
538
511
  await runPromise;
539
512
 
540
513
  const spawnOptions = mockSpawn.mock.calls[0][2];
541
- // env should be process.env directly (no CLAUDE_CODE_EFFORT_LEVEL override)
542
514
  expect(spawnOptions.env).toBe(process.env);
543
515
  });
544
-
545
- it('should support different effort levels', async () => {
546
- for (const level of ['low', 'medium', 'high'] as const) {
547
- const mockProc = createMockProcess();
548
- mockSpawn.mockReturnValue(mockProc);
549
-
550
- const runner = new ClaudeRunner();
551
- const runPromise = runner.run('test prompt', { timeout: 60, effortLevel: level });
552
-
553
- mockProc.emit('close', 0);
554
- await runPromise;
555
-
556
- const spawnOptions = mockSpawn.mock.calls[mockSpawn.mock.calls.length - 1][2];
557
- expect(spawnOptions.env.CLAUDE_CODE_EFFORT_LEVEL).toBe(level);
558
- }
559
- });
560
-
561
- it('should preserve other env vars when effortLevel is set', async () => {
562
- const mockProc = createMockProcess();
563
- mockSpawn.mockReturnValue(mockProc);
564
-
565
- const runner = new ClaudeRunner();
566
- const runPromise = runner.run('test prompt', { timeout: 60, effortLevel: 'medium' });
567
-
568
- mockProc.emit('close', 0);
569
- await runPromise;
570
-
571
- const spawnOptions = mockSpawn.mock.calls[0][2];
572
- // Should have PATH from process.env
573
- expect(spawnOptions.env.PATH).toBe(process.env.PATH);
574
- // And the injected effort level
575
- expect(spawnOptions.env.CLAUDE_CODE_EFFORT_LEVEL).toBe('medium');
576
- });
577
516
  });
578
517
 
579
518
  describe('system prompt append flag', () => {
@@ -8,7 +8,6 @@ import {
8
8
  ConfigValidationError,
9
9
  resolveConfig,
10
10
  getModel,
11
- getEffort,
12
11
  resetConfigCache,
13
12
  } from '../../src/utils/config.js';
14
13
  import { DEFAULT_CONFIG } from '../../src/types/config.js';
@@ -65,8 +64,8 @@ describe('Config Command', () => {
65
64
  expect(() => validateConfig(config)).not.toThrow();
66
65
  });
67
66
 
68
- it('should accept valid config with effort override', () => {
69
- const config = { effort: { plan: 'low' } };
67
+ it('should accept valid config with effortMapping override', () => {
68
+ const config = { effortMapping: { low: 'haiku', medium: 'sonnet' } };
70
69
  expect(() => validateConfig(config)).not.toThrow();
71
70
  });
72
71
 
@@ -85,8 +84,8 @@ describe('Config Command', () => {
85
84
  expect(() => validateConfig(config)).toThrow(ConfigValidationError);
86
85
  });
87
86
 
88
- it('should reject config with invalid effort level', () => {
89
- const config = { effort: { plan: 'max' } };
87
+ it('should reject config with invalid effortMapping model', () => {
88
+ const config = { effortMapping: { low: 'gpt-4' } };
90
89
  expect(() => validateConfig(config)).toThrow(ConfigValidationError);
91
90
  });
92
91
 
@@ -192,7 +191,8 @@ describe('Config Command', () => {
192
191
  it('should have valid default fallback values for config scenario', () => {
193
192
  // These are the values that runConfigSession uses when config loading fails
194
193
  expect(DEFAULT_CONFIG.models.config).toBe('sonnet');
195
- expect(DEFAULT_CONFIG.effort.config).toBe('medium');
194
+ // effortMapping defaults used for per-task model resolution
195
+ expect(DEFAULT_CONFIG.effortMapping.medium).toBe('sonnet');
196
196
  });
197
197
 
198
198
  it('should be able to read raw file contents even when config is invalid JSON', () => {