Repository navigation
Expand file tree
/
Copy pathhooks_agent_spawn.ts
More file actions
723 lines (652 loc) · 55 KB
/
Copy pathhooks_agent_spawn.ts
File metadata and controls
723 lines (652 loc) · 55 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
/** Subagent briefing pack hook. pre_tool_use: When an Agent tool (subagent spawn) fires, append a compact project-context briefing to the subagent's prompt field. The briefing includes a one-line project map, a few cached output IDs to hint at re-use opportunities, and an imperative gate directing the subagent to check for a token-goat command before its first read. Fails open: if building the briefing fails for any reason, the input is passed through unchanged, never blocking a subagent spawn. */
import { createHash } from 'node:crypto'
import * as fs from 'node:fs'
import * as path from 'node:path'
import { claudeConfigDir } from './claude_config_dir.js'
import type { HookEvent } from './hook_registry.js'
import type { HookOutput } from './types.js'
import { dropsResultRewrite, emitRewrite, passOutput, contextOutput, denyOutput, extractToolResultText, getCwd } from './hooks_common.js'
import { buildProjectMap, formatProjectMap } from './baseline.js'
import { neutralizeSpokenMarkers } from './injection_scan.js'
import { getOutstandingAgentSpawns, getSessionBashOutputs, markHintShown, recordOutstandingAgentSpawn, removeOutstandingAgentSpawn, wasHintShown } from './session.js'
import { getBashOutput } from './bash_output_cache.js'
import { estimateTokens } from './compact.js'
import { sliceToEstimatedTokens } from './overflow_guard.js'
import { toKB } from './util.js'
import { mcpHash, mcpOutputId, storeMcpOutput } from './mcp_cache.js'
import { recordStat, savedTokensFromBytes } from './stats.js'
import { redactSecrets } from './secret_redact.js'
import { loadConfig } from './config.js'
import { isRewriteWorthwhile, resolveMinNetSavingsBytes } from './tool_filters/index.js'
import { getHarnessName } from './bridges/registry.js'
import { isInsideRoot } from './project.js'
import { agentTypeOf, permissionNeutralRewrite } from './rewrite_permission.js'
import { echoedValue } from './hint_suggestion_guard.js'
import type * as AgentReceiptModule from './agent_receipt.js'
// Loaded on first use: the hook entry parses every eager byte on each tool call, and a receipt is only looked for when a subagent stops or its result arrives.
const loadAgentReceipt = (): Promise<typeof AgentReceiptModule> => import('./agent_receipt.js')
/** Target token budget for the entire briefing (project map + cached ids + reminder + report contract). Measured against this repo's own compact map (46 tokens) plus a realistic mid-size project's compact map (~140 tokens, e.g. "Files: 640" + 10 top symbols) combined with the imperative surgical-read reminder (136 tokens, grown from a one-liner in c574b1f6), the report contract added below (~95 tokens), and a 1-3 entry cache-ids block (26-50 tokens): worst-case realistic total lands around 400-470 tokens. 450 left too little headroom once the contract was added, so 550 leaves a real margin above that; revisit this number again if either tail block grows further. */
const BRIEFING_TARGET_TOKENS = 550
/** How many cached outputs the briefing names. */
const CACHED_IDS_LISTED = 3
/** Longest command text shown beside a cached id; the full command is one recall away. */
const CACHED_COMMAND_PREVIEW_CHARS = 60
/** Briefing project map cache: avoiding repeated recursive directory traversal across subagent spawns. */
const PROJECT_MAP_BRIEFING_TTL_MS = 300_000
const PROJECT_MAP_BRIEFING_CACHE_MAX = 16
const projectMapBriefingCache = new Map<string, { createdAt: number; text: string }>()
function cachedProjectMapBriefing(projectRoot: string): string {
const root = path.resolve(projectRoot)
const now = Date.now()
for (const [key, value] of projectMapBriefingCache) {
if (now - value.createdAt >= PROJECT_MAP_BRIEFING_TTL_MS) projectMapBriefingCache.delete(key)
}
const hit = projectMapBriefingCache.get(root)
if (hit !== undefined) {
projectMapBriefingCache.delete(root)
projectMapBriefingCache.set(root, hit)
return hit.text
}
const map = buildProjectMap(root, { compact: true })
const text = formatProjectMap(map, map.compact)
projectMapBriefingCache.set(root, { createdAt: Date.now(), text })
while (projectMapBriefingCache.size > PROJECT_MAP_BRIEFING_CACHE_MAX) {
const oldest = projectMapBriefingCache.keys().next().value
if (oldest === undefined) break
projectMapBriefingCache.delete(oldest)
}
return text
}
export function resetProjectMapBriefingCache(): void {
projectMapBriefingCache.clear()
}
/** " (~2KB, 12m ago, `git status`)": size, age and a one-line preview of the command, so a subagent can tell which id answers its question. The command was redacted when it was stored (bash_output_cache.ts); it is flattened to one line and defanged here because it lands in a prompt. */
function describeCachedOutput(entry: { command: string; output: string; storedAt: number }): string {
const ageMin = Math.max(0, Math.round((Date.now() - entry.storedAt) / 60_000))
const age = ageMin < 60 ? `${ageMin}m` : ageMin < 60 * 48 ? `${Math.round(ageMin / 60)}h` : `${Math.round(ageMin / 1440)}d`
const flat = neutralizeSpokenMarkers(entry.command.replace(/\s+/g, ' ').trim())
const preview = flat.length > CACHED_COMMAND_PREVIEW_CHARS ? flat.slice(0, CACHED_COMMAND_PREVIEW_CHARS) + '...' : flat
return ` (~${toKB(entry.output.length)}KB, ${age} ago, ${'`'}${preview.replace(/`/g, "'")}${'`'})`
}
/** Build a compact subagent briefing block. Returns a brief formatted string with: 1. One-line project-map summary (top-level structure only) 2. 2-3 recent cached output IDs as re-use hints 3. One-line surgical-read reminder Returns empty string if the briefing cannot be built (project unavailable, etc.). Estimated length is kept under BRIEFING_TARGET_TOKENS for efficient context usage. `projectRoot` is the directory the map summary walks, and null skips the map. See {@link briefingRoot} for why that is not always process.cwd(). */
function buildSubagentBriefing(projectRoot: string | null): string {
try {
const head: string[] = []
head.push('')
head.push('## Session briefing (for context)')
// 1. Project map summary
try {
if (projectRoot === null) throw new Error('no project root')
const mapText = cachedProjectMapBriefing(projectRoot)
head.push(mapText)
} catch {
// Project map unavailable — skip it and continue with cached ids/reminder
}
// 2. Recent cached output IDs (2-3 most recent) -- built separately from `head`/`tail` so it can be dropped as a whole when over budget, without touching either.
let cacheIdsBlock = ''
try {
const outputs = getSessionBashOutputs()
if (outputs.length > 0) {
// Newest first, and only ids that still resolve: the session remembers an id after its blob has aged out or been evicted, and a briefing that hands a subagent a dead id costs it a failed recall.
const live: string[] = []
for (const [, id] of [...outputs].reverse()) {
const entry = getBashOutput(id)
if (entry === null) continue
live.push('`token-goat bash-output ' + id + '`' + describeCachedOutput(entry))
if (live.length === CACHED_IDS_LISTED) break
}
if (live.length > 0) cacheIdsBlock = '\n\nCached outputs this session: ' + live.join(', ')
}
} catch {
// Bash output unavailable — skip and continue with reminder
}
// 3. Surgical-read reminder, plus the report-contract clause. Both are load-bearing (dropped only in the last-resort tail-slice below, after the cache-ids block is already gone) -- the contract is what makes a spawned subagent's report cite evidence instead of pasting it, and its "state every unverified claim explicitly" clause is what has caught a subagent shipping something it never checked, three cycles running.
const tail: string[] = []
tail.push('')
tail.push('Before your first read of any file, check for a token-goat command that returns just what you need and run it instead of a full-file read or wide grep: `token-goat symbol <name>`, `token-goat read "file::symbol"`, `token-goat section "file::<heading>"`, `token-goat json-query file \'a.b.c\'`. Skipping that check is a violation, not an oversight; the only exemptions are a file under ~200 lines you need whole, a never-indexed file, or an image.')
tail.push('')
tail.push('Report contract: cite evidence as `file::symbol` or a token-goat recall id (`token-goat mcp-output <id> --full`) rather than pasting bodies; paste a fenced block only when the exact bytes are load-bearing; state every unverified claim explicitly (e.g. "not verified: ...") rather than omitting it.')
const withCacheIds = head.join('\n') + cacheIdsBlock + '\n' + tail.join('\n')
if (estimateTokens(withCacheIds) <= BRIEFING_TARGET_TOKENS) {
return withCacheIds
}
// Over budget: drop the cache-ids block first -- it's the nice-to-have re-use hint, not the load-bearing map/reminder content -- and re-check before falling back to a lossy trim.
const withoutCacheIds = head.join('\n') + '\n' + tail.join('\n')
const tokens = estimateTokens(withoutCacheIds)
if (tokens <= BRIEFING_TARGET_TOKENS) {
return withoutCacheIds
}
// Still over budget with the map alone (e.g. a very large project tree): trim from the end as a last resort. This can still cut into the reminder, but only once dropping the cache-ids block was already insufficient, not as the first thing tried.
return sliceToEstimatedTokens(withoutCacheIds, BRIEFING_TARGET_TOKENS)
} catch {
// Any error during briefing construction: fail open
return ''
}
}
/** Word-set Jaccard similarity threshold above which two Agent-spawn prompts are treated as near-duplicates. Chosen high (0.75, within the recommended 0.7-0.8 range) to bias hard against false positives: two genuinely different subagent tasks that merely share some vocabulary (both mention "fix", "the file", "tests", ...) must never trip this. A missed true duplicate only costs a nice-to-have warning; a false "duplicate!" on two real, different tasks is actively annoying and erodes trust in the hint. */
const DUPLICATE_PROMPT_JACCARD_THRESHOLD = 0.75
/** Normalize `text` into its lowercase, punctuation-stripped word set for Jaccard comparison. */
function promptWordSet(text: string): Set<string> {
const words = text
.toLowerCase()
.replace(/[^\p{L}\p{N}\s]+/gu, ' ')
.split(/\s+/)
.filter((w) => w.length > 0)
return new Set(words)
}
/** Word-set Jaccard similarity: |intersection| / |union|, 0 when either side has no words. */
function jaccardSimilarity(a: ReadonlySet<string>, b: ReadonlySet<string>): number {
if (a.size === 0 || b.size === 0) return 0
let intersection = 0
for (const word of a) {
if (b.has(word)) intersection++
}
const union = a.size + b.size - intersection
return union === 0 ? 0 : intersection / union
}
/** Find an already-outstanding Agent-spawn prompt this session that is a near-duplicate of `prompt` (Jaccard similarity >= {@link DUPLICATE_PROMPT_JACCARD_THRESHOLD}), or null if none. */
function findDuplicateOutstandingPrompt(prompt: string): string | null {
const words = promptWordSet(prompt)
for (const entry of getOutstandingAgentSpawns()) {
if (jaccardSimilarity(words, promptWordSet(entry.prompt)) >= DUPLICATE_PROMPT_JACCARD_THRESHOLD) {
return entry.prompt
}
}
return null
}
/** Truncate `text` to `max` chars for embedding in the advisory warning, appending an ellipsis when cut. */
function truncateForWarning(text: string, max: number): string {
return text.length > max ? text.slice(0, max) + '...' : text
}
/** The directory a spawn briefing's project map walks, or null to leave the map out. On VS Code it is the workspace folder the payload names and nothing else: with no folder open VS Code sends no cwd and starts the hook in the home directory, so process.cwd() there would walk $HOME ahead of the approval prompt. Every other harness keeps process.cwd(), as before. */
function briefingRoot(event: HookEvent): string | null {
if (getHarnessName() === 'vscode') return getCwd(event) ?? null
return process.cwd()
}
/** True when the hooks file this call came through also wires the harness's subagent-start hook, which delivers the spawn briefing into the subagent's own context. The briefing then stays out of the spawning tool call, whose rewritten arguments the parent keeps in its history. Read from the file rather than assumed from the version, because a hooks file written before the key existed is only rewritten by the next install. */
export function subagentStartWired(): boolean {
const harness = getHarnessName()
// Both names spelled out as the shim sets them (copilot_cli.ts), the VS Code one being vscode_duplicate.ts's VSCODE_HOOKS_DIR_ENV: importing that module put it in the hook entry's eager chunk set past dist_chunks_deduped's ceiling. The shim-driven "unrewritten once wired" tests in copilot_subagent_start.test.ts fail if either drifts.
const dirVar = harness === 'copilot_cli' ? 'TOKEN_GOAT_COPILOT_HOOKS_DIR' : harness === 'vscode' ? 'TOKEN_GOAT_VSCODE_HOOKS_DIR' : undefined
const dir = dirVar === undefined ? undefined : process.env[dirVar]
if (dir === undefined || dir === '') return false
try {
const config = JSON.parse(fs.readFileSync(path.join(dir, 'token-goat.json'), 'utf8')) as { hooks?: Record<string, unknown> }
const entries = config.hooks?.[harness === 'vscode' ? 'SubagentStart' : 'subagentStart']
return Array.isArray(entries) && entries.length > 0
} catch {
return false
}
}
/** subagent_start: the spawn briefing as context for the subagent being started. Copilot CLI 1.0.88 prepends a subagentStart additionalContext to the subagent's prompt (capture C4a); VS Code 1.137 passes SubagentStart's hookSpecificOutput.additionalContext to the subagent request (extension.js executeSubagentStartHook). */
export function subagentStartHandler(event: HookEvent): HookOutput {
try {
const root = getCwd(event) ?? (getHarnessName() === 'vscode' ? null : process.cwd())
const briefing = buildSubagentBriefing(root).trim()
return briefing ? contextOutput(briefing) : passOutput()
} catch {
return passOutput()
}
}
/** Every tool that spawns a subagent, with the input field that carries its brief. Claude Code's Agent (and its older name Task) and Copilot CLI's task take `prompt`; Codex's `spawn_agent` takes `message` or `items` (codex-rs/core/src/tools/handlers/multi_agents_spec.rs::spawn_agent_common_properties_v1) and reaches the hook under that name, with `Agent` only a matcher alias (codex-rs/core/src/tools/hook_names.rs, registry.rs::function_hook_tool_name). The one table the handlers and the registrations at the foot of this file both read. */
const SPAWN_TOOL_BRIEF_FIELD: Readonly<Record<string, string>> = { Agent: 'prompt', task: 'prompt', Task: 'prompt', spawn_agent: 'message' }
function isAgentTool(toolName: string | undefined): boolean {
return toolName !== undefined && Object.hasOwn(SPAWN_TOOL_BRIEF_FIELD, toolName)
}
/** A spawn's brief as written, and how to add text after it. */
interface SpawnBrief {
readonly text: string
readonly withSuffix: (suffix: string) => Record<string, unknown>
}
/** The brief a spawn call carries, or null when it carries none. A Codex spawn that sends `items` instead of `message` has its text items joined, and the suffix is added as one more text item so the structured items before it are left alone. */
function readSpawnBrief(toolName: string | undefined, toolInput: Record<string, unknown>): SpawnBrief | null {
const field = SPAWN_TOOL_BRIEF_FIELD[toolName ?? '']
if (field === undefined) return null
const written = toolInput[field]
if (typeof written === 'string' && written.trim()) return { text: written, withSuffix: (suffix) => ({ ...toolInput, [field]: written + suffix }) }
const items = toolInput['items']
if (toolName !== 'spawn_agent' || !Array.isArray(items)) return null
const joined = items.flatMap((item: { type?: unknown; text?: unknown } | null) => (item?.type === 'text' && typeof item.text === 'string' ? [item.text] : [])).join(' ')
if (!joined.trim()) return null
return { text: joined, withSuffix: (suffix) => ({ ...toolInput, items: [...items, { type: 'text', text: suffix }] }) }
}
export function preAgentHandler(event: HookEvent): HookOutput {
// Only fire on a subagent spawn tool
if (!isAgentTool(event.toolName)) return passOutput()
const toolInput = event.toolInput
const brief = readSpawnBrief(event.toolName, toolInput)
// Skip if the brief is missing or empty
if (brief === null) return passOutput()
const prompt = brief.text
try {
// Ahead of the outstanding-spawn registration: a denied call never runs, so registering it would flag its own retry as a near-duplicate.
const scopedDeny = buildScopedSpawnDeny(toolInput, getCwd(event))
if (scopedDeny) return scopedDeny
// Check for a near-duplicate BEFORE registering this prompt, so a spawn never flags itself.
const duplicateOf = findDuplicateOutstandingPrompt(prompt)
recordOutstandingAgentSpawn(prompt)
// Delivered by subagentStartHandler instead when that hook is wired, so it never lands in the parent's copy of the call.
const briefing = subagentStartWired() ? '' : buildSubagentBriefing(briefingRoot(event))
const advisory = duplicateOf
? `\n\n[token-goat] A similar subagent spawn already appears to be outstanding this session (prompt starts: ${echoedValue(neutralizeSpokenMarkers(truncateForWarning(duplicateOf, 80)))}). This is advisory only -- proceeding is fine if intentional.`
: ''
// If there is nothing to add (briefing failed to build and no duplicate warning), pass through unchanged
if (!briefing && !advisory) return passOutput()
// Append briefing and/or duplicate-spawn advisory to the brief
const updatedPrompt = prompt + briefing + advisory
const updatedInput = brief.withSuffix(briefing + advisory)
// The prompt is all that changes and Agent rules match the subagent type, so the rewrite carries no permission decision; rewrite_permission.ts declines it only when a rule could look further.
return permissionNeutralRewrite(updatedInput, { kind: 'agent', harness: getHarnessName(), mode: event.raw['permission_mode'], cwd: getCwd(event) ?? process.cwd(), original: prompt, rewritten: updatedPrompt, agentType: agentTypeOf(event.raw) }) ?? passOutput()
} catch {
// Any unexpected error: fail open, never block the spawn
return passOutput()
}
}
// Thresholds live in config (agent_report.*, see config.ts) rather than as literals here so an operator can retune or disable envelope compaction without a rebuild, matching how every other compaction subsystem in this codebase is tuned. A subagent's report is already-distilled PROSE with no safe way to shrink it losslessly, so prose is never touched by this handler -- caveats, limitations, and "I did not verify X" admissions live there, and those are precisely the sentences that catch a subagent shipping something it did not check (three consecutive self-improvement cycles caught a real defect exactly that way). What IS safely reducible is what agents paste INTO fenced blocks: gate transcripts, `git diff --stat` tables, dogfood output. Those are mechanically reproducible from the repo, and the full text stays one `mcp-output <id> --full` away, so eliding their middle costs the parent nothing it cannot recover on demand.
// A fence line per CommonMark: up to 3 leading spaces, then a run of 3+ backticks or 3+ tildes, then an optional info string. Capturing the run (not just "starts with ```") is what makes nesting safe -- see collapseFencedBlocks. The info-string tail is `[^\n]*`, not `.*`, for the same reason markdown_lines.ts's eachUnfencedLine uses it: a JS regex `.` excludes `\r`, so a CRLF-terminated fence line (a report that pasted Windows command output into a block) matched nothing and every fenced block went uncollapsed.
const FENCE_LINE_RE = /^ {0,3}(`{3,}|~{3,})([^\n]*)$/
interface FencedBlockLines {
/** Line index of the opening fence marker. */
fenceStart: number
/** Line index of the closing fence marker (inclusive). */
closerIndex: number
}
// Shared CommonMark-following fence scanner used by both collapseFencedBlocks and dedupeFencedBlocks, so both stay in agreement about where a complete fenced block begins and ends: an unterminated trailing fence (no closer) is deliberately NOT reported as a block by either caller -- see collapseFencedBlocks's own comment for why.
function findFencedBlockLines(lines: readonly string[]): FencedBlockLines[] {
const blocks: FencedBlockLines[] = []
let fenceStart = -1
let openMarker = ''
for (let i = 0; i < lines.length; i++) {
const line = lines[i]!
const match = FENCE_LINE_RE.exec(line)
if (fenceStart === -1) {
if (match !== null) {
fenceStart = i
openMarker = match[1]!
}
continue
}
const isCloser =
match !== null &&
match[1]![0] === openMarker[0] &&
match[1]!.length >= openMarker.length &&
match[2]!.trim() === ''
if (!isCloser) continue
blocks.push({ fenceStart, closerIndex: i })
fenceStart = -1
}
return blocks
}
// Collapse the middle of over-long fenced code blocks, leaving every non-fenced line byte-identical. Fence matching follows CommonMark rather than a naive ```-toggle, because agent reports routinely quote markdown AT us: a report that pastes a snippet containing its own ``` fence, or wraps an example in a 4-backtick fence, would close a toggle at the wrong line and mis-slice the surrounding prose. A block therefore ends only at a fence of the SAME character, at least as long as the opener, carrying no info string; anything else inside is content. An unterminated fence at end-of-text is emitted verbatim rather than collapsed, since without a closing marker there is no way to tell a code block from prose that merely began with a fence.
export function collapseFencedBlocks(text: string, recallHint: string, minLines: number, keepLines: number): string {
const lines = text.split('\n')
const blocks = findFencedBlockLines(lines)
const out: string[] = []
let cursor = 0
for (const { fenceStart, closerIndex } of blocks) {
out.push(...lines.slice(cursor, fenceStart))
const bodyLines = closerIndex - fenceStart - 1
if (bodyLines > minLines) {
out.push(...lines.slice(fenceStart, fenceStart + 1 + keepLines))
out.push(`[token-goat: ${bodyLines - keepLines * 2} lines elided -- full report via ${recallHint}]`)
out.push(...lines.slice(closerIndex - keepLines, closerIndex + 1))
} else {
out.push(...lines.slice(fenceStart, closerIndex + 1))
}
cursor = closerIndex + 1
}
// Whatever follows the last complete block -- including an unterminated trailing fence -- is emitted verbatim: with no closing marker there is no way to tell a real code block from prose that merely began with a backtick line, and this handler never guesses at the parent's expense.
out.push(...lines.slice(cursor))
return out.join('\n')
}
// Intra-report cross-fence dedup: when the SAME complete fenced-block body (byte-for-byte) appears more than once in one report, every occurrence after the first is replaced with a marker pointing at the cached full report -- never at "block N", since mcp-output has no way to address an individual block. Deliberately intra-report only: comparing across sessions/reports would be "the gate was not re-run", the exact admission this design exists to preserve, not a savings opportunity. Body hashes are computed from `original` (pre-collapse) so two blocks that only look alike after collapseFencedBlocks elided their middles are never mistaken for duplicates; block BOUNDARIES for the actual replacement are read from `collapsed` (post-collapse) so a marker never points at a block whose visible content collapseFencedBlocks already elided out from under it -- running dedup after collapse, on collapse's own output, is what keeps that in sync.
export function dedupeFencedBlocks(collapsed: string, original: string, recallHint: string): string {
const originalLines = original.split('\n')
const originalBlocks = findFencedBlockLines(originalLines)
if (originalBlocks.length < 2) return collapsed
const collapsedLines = collapsed.split('\n')
const collapsedBlocks = findFencedBlockLines(collapsedLines)
// Structural mismatch (should not happen: collapseFencedBlocks never adds or removes fence boundaries) -- fail safe by declining to touch anything rather than guessing at an index.
if (collapsedBlocks.length !== originalBlocks.length) return collapsed
const bodyHashes = originalBlocks.map(({ fenceStart, closerIndex }) =>
createHash('sha256').update(originalLines.slice(fenceStart + 1, closerIndex).join('\n')).digest('hex'),
)
const firstOccurrenceOf = new Map<string, number>()
const out: string[] = []
let cursor = 0
let dedupedAny = false
for (let i = 0; i < collapsedBlocks.length; i++) {
const { fenceStart, closerIndex } = collapsedBlocks[i]!
const hash = bodyHashes[i]!
if (!firstOccurrenceOf.has(hash)) {
firstOccurrenceOf.set(hash, i)
out.push(...collapsedLines.slice(cursor, closerIndex + 1))
} else {
out.push(...collapsedLines.slice(cursor, fenceStart))
out.push(`[token-goat: identical bytes to an earlier block in this report -- full report via ${recallHint}]`)
dedupedAny = true
}
cursor = closerIndex + 1
}
out.push(...collapsedLines.slice(cursor))
return dedupedAny ? out.join('\n') : collapsed
}
/** Number of consecutive blank lines kept when a longer run is collapsed -- fixed, not configurable: this is deliberately the "safe half" of blank-line handling with no tunable surface. */
const BLANK_RUN_KEEP = 2
// Collapse runs of MORE THAN two blank lines to exactly two, but ONLY inside fenced blocks -- never touching prose, which stays byte-identical per the core design rule. No count marker (a blank line carries no evidence or caveat worth pointing a recall hint at) and no recomputation of anything: this deliberately runs LAST, after collapseFencedBlocks and dedupeFencedBlocks have already finished, on their combined output -- never before slicing -- so it can never perturb the bodyLines count collapseFencedBlocks used to decide what to elide, nor the `keep_lines <= floor((min_lines-1)/2)` clamp that keeps that math from going negative (see config.ts). Explicitly NOT dedupeConsecutive (src/tool_filters/helpers.ts): that helper's default `${line} (×${count})` formatter would inject a token-goat annotation into a region this design promises stays byte-identical.
export function collapseBlankRunsInFences(text: string): string {
const lines = text.split('\n')
const blocks = findFencedBlockLines(lines)
if (blocks.length === 0) return text
const out: string[] = []
let cursor = 0
let changedAny = false
for (const { fenceStart, closerIndex } of blocks) {
out.push(...lines.slice(cursor, fenceStart + 1))
let blankRun = 0
for (let i = fenceStart + 1; i < closerIndex; i++) {
const line = lines[i]!
if (line === '') {
blankRun++
if (blankRun <= BLANK_RUN_KEEP) out.push(line)
else changedAny = true
} else {
blankRun = 0
out.push(line)
}
}
out.push(lines[closerIndex]!)
cursor = closerIndex + 1
}
out.push(...lines.slice(cursor))
return changedAny ? out.join('\n') : text
}
/** Session-hint dedupe key for the unrestricted-spawn advisory below: fires at most once per session. */
const SPAWN_RESTRICT_HINT_KEY = 'agent-spawn-restrict-hint'
/** How many restricted agent names the advisory lists by name before collapsing the rest into a count. */
const SPAWN_RESTRICT_MAX_NAMES = 3
/** Depth cap for the roster walk. The common layouts are flat files in ~/.claude/agents and symlinked collection directories one level down, so 4 leaves margin without letting a pathological tree run away. */
const ROSTER_WALK_MAX_DEPTH = 4
/** Hard cap on definition files parsed per scan, so a mispointed or gigantic roster directory cannot stall a post-tool hook. */
const ROSTER_WALK_MAX_FILES = 400
/** The shape an agent name has to have before it is allowed into a model-facing advisory: the identifier charset real rosters use, colons included for plugin-scoped names, capped so a single definition cannot fill the notice. */
const AGENT_NAME_RE = /^[A-Za-z0-9._:-]{1,64}$/
/** Parse a Claude Code agent-definition markdown file's YAML frontmatter, answering the one question the unrestricted-spawn advisory needs: does this definition carry a `tools:` allowlist? Corpus measurement (loop 48, 5,988 lanes) showed the allowlist is the causal lever on spawn-prefix cost: an agent WITHOUT one inherits every tool and MCP schema into its lane's system prompt, and typing alone changes nothing. Returns null when the file has no parseable frontmatter at all. `restricted` means: a `tools:` key exists and its value is neither empty nor the inherit-everything `*`. Both the inline comma-list form and the indented block-list form count; a `tools:` line with no value and no block items is treated as absent (unrestricted), the conservative direction for a gate whose false positive would recommend an agent that saves nothing. */
export function parseAgentDefinition(text: string, fallbackName: string): { name: string; restricted: boolean } | null {
const fmMatch = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/.exec(text)
if (!fmMatch) return null
const fm = fmMatch[1] as string
// `(.*)$` under /m stops before \n but captures a trailing \r, so every capture below is trimmed before use (see the CRLF line-end-predicate defect class).
const nameMatch = /^name:(.*)$/m.exec(fm)
const rawName = nameMatch ? (nameMatch[1] as string).trim().replace(/^["']|["']$/g, '') : ''
// Both the frontmatter `name:` and the file basename behind it are repository-authored now that the project roster is a scan root, and whichever wins is interpolated into an advisory that reaches the model in token-goat's own `[token-goat]` voice through a channel that neither fences nor neutralizes. So the value has to be shaped like an agent name before it is allowed to speak: anything else is not a name we can recommend, and a definition we cannot name is dropped rather than passed through.
const resolved = AGENT_NAME_RE.test(rawName) ? rawName : fallbackName
if (!AGENT_NAME_RE.test(resolved)) return null
const name = resolved
const toolsMatch = /^tools:(.*)$/m.exec(fm)
if (!toolsMatch) return { name, restricted: false }
const inline = (toolsMatch[1] as string).trim()
if (inline === '*' || inline === '"*"' || inline === "'*'") return { name, restricted: false }
if (inline !== '') return { name, restricted: true }
// Bare `tools:` line: the allowlist, if any, is an indented block list on the following lines. Stop at the first non-indented line, which is the next top-level frontmatter key.
const after = fm.slice(toolsMatch.index + toolsMatch[0].length)
for (const line of after.split(/\r?\n/)) {
if (/^\s+-\s*\S/.test(line)) return { name, restricted: true }
if (/^\S/.test(line)) break
}
return { name, restricted: false }
}
/** Scan the machine-level agent roster (~/.claude/agents, recursively, following symlinked collection directories with a realpath cycle guard) and return the sorted names of every definition that carries a `tools:` allowlist. This is the advisory's existence gate: with no restricted definition on the machine there is nothing actionable to recommend, and an unclearable warning trains the user to ignore every warning the tool emits. Both the home roster and the project's own <projectDir>/.claude/agents are scanned (projectDir is the cwd the hook payload names, so a resident server's start directory or a payload from another project never picks the roster; process.cwd() only when the payload names none): the project roster holds exactly the definitions a spawn in that repo should be reaching for, and scanning it is what makes every name here potentially repository-authored rather than user-authored, which is why parseAgentDefinition constrains the name's shape before it can reach a model-facing advisory. */
export function findRestrictedAgentNames(roots?: readonly string[], projectDir: string = process.cwd()): string[] {
// The project roster is scanned alongside the home one because a repo's own .claude/agents holds exactly the definitions a spawn in that repo should be reaching for, and a home-only default made them invisible to the advisory: this repo carries three such definitions and the advisory named none of them. Duplicate roots are harmless, since the visited set below folds them.
const projectAgentsRoot = path.join(projectDir, '.claude', 'agents')
const scanRoots = roots ?? [path.join(claudeConfigDir(), 'agents'), projectAgentsRoot]
const names = new Set<string>()
const visited = new Set<string>()
let filesSeen = 0
// confineTo bounds a walk to a resolved directory: null for the home roster (the user controls it directly and may legitimately symlink it, or an entry inside it, to a personal collection elsewhere on their own machine -- the whole point of following symlinked collection directories below), non-null for the project roster, whose content is repository-authored. Without this, a checked-in `.claude/agents/x -> /` (or any other absolute target) let a cloned repository's own roster walk follow the link and read arbitrary `.md` files anywhere else reachable on the machine, surfacing their frontmatter `name:` in a model-facing advisory -- the same escape-via-nested-symlink shape cli_bootstrap_audit.ts's scanMetadataRoot already refuses for its own roster walk.
const walk = (dir: string, depth: number, confineTo: string | null): void => {
if (depth > ROSTER_WALK_MAX_DEPTH || filesSeen >= ROSTER_WALK_MAX_FILES) return
let real: string
try {
real = fs.realpathSync(dir)
} catch {
return
}
if (confineTo !== null && !isInsideRoot(real, confineTo)) return
const key = process.platform === 'win32' ? real.toLocaleLowerCase() : real
if (visited.has(key)) return
visited.add(key)
let entries: fs.Dirent[]
try {
entries = fs.readdirSync(dir, { withFileTypes: true })
} catch {
return
}
for (const entry of entries) {
if (filesSeen >= ROSTER_WALK_MAX_FILES) return
const full = path.join(dir, entry.name)
// statSync rather than the Dirent flags because a symlinked collection directory reports isDirectory() false on its Dirent; the visited-set above keeps a link cycle from recursing forever.
let stat: fs.Stats
try {
stat = fs.statSync(full)
} catch {
continue
}
if (stat.isDirectory()) {
walk(full, depth + 1, confineTo)
continue
}
if (!stat.isFile() || !entry.name.toLowerCase().endsWith('.md')) continue
filesSeen++
let text: string
try {
text = fs.readFileSync(full, 'utf-8')
} catch {
continue
}
const parsed = parseAgentDefinition(text, path.basename(entry.name, path.extname(entry.name)))
if (parsed !== null && parsed.restricted) names.add(parsed.name)
}
}
for (const root of scanRoots) {
const isProjectRoot = roots === undefined && path.resolve(root) === path.resolve(projectAgentsRoot)
if (!isProjectRoot) {
walk(root, 0, null)
continue
}
// The root itself may not be a symlink either: a repo replacing its own `.claude/agents` entry with a link is the same escape with one fewer step than a nested link.
let rootIsLink: boolean
try {
rootIsLink = fs.lstatSync(root).isSymbolicLink()
} catch {
continue
}
if (rootIsLink) continue
let confineTo: string | null
try {
confineTo = fs.realpathSync(root)
} catch {
continue
}
walk(root, 0, confineTo)
}
return Array.from(names).sort()
}
/** Build the once-per-session unrestricted-spawn advisory, or '' when it does not apply. Trigger: the finished spawn ran as general-purpose, either because `subagent_type` was absent (620 of 3,167 corpus spawn blocks) or because it named general-purpose explicitly; both are definitionally unrestricted with no definition file to resolve, which is the only restriction status observable at the hook without reading a roster file for the spawned type. Gate: at least one tools-restricted agent definition exists in ~/.claude/agents, so the advice is actionable and the hint clearable. Dedupe: once per session via the persisted hints-shown set. Accounting: recorded as a zero-credit `session_hint`. The advisory fires AFTER the spawn it observed and cannot save that spawn: the counterfactual it might improve (the user's next spawn, or their roster) is not a branch this code blocks, so crediting anything would repeat the advisory-credited-the-full-file defect class. The text says so explicitly for the same reason. */
export function buildUnrestrictedSpawnAdvisory(toolInput: Record<string, unknown>, projectDir?: string): string {
try {
// Gated off entirely on Copilot CLI because the advisory's content is Claude Code's Task schema (subagent_type, ~/.claude/agents rosters). Copilot's own task tool carries agent_type, not subagent_type (captured toolArgs {description, prompt, agent_type, name}, tg-captures C4a), so the absent-field trigger would misclassify every Copilot task spawn as an untyped general-purpose spawn. The channel is not the reason: post_tool_use additionalContext does reach the model on Copilot 1.0.88 (tg-captures C1a). Other bridges are not gated here: their task-tool wire shapes are unverified (loop-ledger BE-06) and their bridges forward additionalContext, so suppressing them would rest on inference. VS Code is gated for the same schema reason, read off its own bundle: runSubagent takes {prompt, description, agentName, model} (RunSubagentTool.getToolData in VS Code 1.137.0's workbench.desktop.main.js), where agentName names a VS Code chat agent, so advice to pass a ~/.claude/agents name as subagent_type names a key the tool does not have.
const harness = getHarnessName()
if (harness === 'copilot_cli' || harness === 'vscode') return ''
const rawType = toolInput['subagent_type']
const spawnType = typeof rawType === 'string' ? rawType.trim() : ''
if (spawnType !== '' && spawnType !== 'general-purpose') return ''
if (wasHintShown(SPAWN_RESTRICT_HINT_KEY)) return ''
const names = findRestrictedAgentNames(undefined, projectDir)
if (names.length === 0) return ''
markHintShown(SPAWN_RESTRICT_HINT_KEY)
recordStat('session_hint', 0, 0, undefined, 'agent-spawn-restrict')
// Neutralized even though AGENT_NAME_RE already excludes `[`, because this is the layer that survives someone widening that charset later: only the interpolated names go through it, never the sentence around them, since our own `[token-goat]` prefix is exactly what the neutralizer is built to strip.
const shown = neutralizeSpokenMarkers(names.slice(0, SPAWN_RESTRICT_MAX_NAMES).join(', '))
const more = names.length > SPAWN_RESTRICT_MAX_NAMES ? ` and ${names.length - SPAWN_RESTRICT_MAX_NAMES} more` : ''
return `[token-goat] This spawn ran as general-purpose (the default when subagent_type is omitted), which is unrestricted: its lane starts by paying for every tool and MCP schema on the machine. Tools-restricted agent definitions exist here: ${shown}${more}. A future spawn that fits one of them can pass that name as subagent_type to start with a much smaller prefix. Advisory only: this spawn has already run, and this notice saved nothing.`
} catch {
return ''
}
}
/** Session-hint dedupe key for the opt-in scoped-spawn deny: it refuses at most one spawn per session, so re-issuing the same call is always a way through. */
const SCOPED_SPAWN_DENY_KEY = 'agent-scoped-spawn-deny'
/** The pre-tool counterpart of {@link buildUnrestrictedSpawnAdvisory}, behind `hints.agent_scoped_spawn_deny` (off by default). The advisory can only describe a spawn that has already paid for its unrestricted prefix; this refuses the first untyped spawn of a session before it runs and names the restricted definitions, so the retry can pick one. Narrower than the advisory on purpose: only an OMITTED subagent_type triggers it, since an explicit `general-purpose` is a choice the caller made, and a refusal that overrode a choice would just be re-issued. Once per session, so the promise the message makes -- re-issue unchanged and it runs -- is kept by construction. Harness-gated exactly as the advisory is, for the same schema reason. Returns null when it does not fire. */
function buildScopedSpawnDeny(toolInput: Record<string, unknown>, projectDir?: string): HookOutput | null {
if (!loadConfig().hints.agent_scoped_spawn_deny) return null
const harness = getHarnessName()
if (harness === 'copilot_cli' || harness === 'vscode') return null
const rawType = toolInput['subagent_type']
if (typeof rawType === 'string' && rawType.trim() !== '') return null
if (wasHintShown(SCOPED_SPAWN_DENY_KEY)) return null
const names = findRestrictedAgentNames(undefined, projectDir)
if (names.length === 0) return null
markHintShown(SCOPED_SPAWN_DENY_KEY)
// The post-tool advisory would name the same definitions again after the retry runs; the deny has already said it.
markHintShown(SPAWN_RESTRICT_HINT_KEY)
recordStat('agent_scoped_spawn_deny', 0, 0)
const shown = neutralizeSpokenMarkers(names.slice(0, SPAWN_RESTRICT_MAX_NAMES).join(', '))
const more = names.length > SPAWN_RESTRICT_MAX_NAMES ? ` and ${names.length - SPAWN_RESTRICT_MAX_NAMES} more` : ''
return denyOutput(`This Agent call omits subagent_type, so it would run as general-purpose, which is unrestricted: its lane starts by paying for every tool and MCP schema on the machine. Tools-restricted agent definitions exist here: ${shown}${more}. Re-issue the call with one of them as subagent_type if it fits the task. If none fits, re-issue it unchanged and it will run: this refusal fires once per session.`)
}
/** The notice both report rewrites append, built in one place so {@link REWRITTEN_REPORT_RE} can recognize it. */
function reportNotice(resultText: string, recallHint: string, spawnAdvisory: string): string {
return `[token-goat] This subagent report (${toKB(resultText.length)}KB) is cached for later recall: ${recallHint}${spawnAdvisory === '' ? '' : `\n${spawnAdvisory}`}`
}
/** A report that already ends in the notice of a rewrite token-goat made, with or without the receipt lines (`token-goat: ...`) that reportNotice appends after the recall hint. On Copilot CLI the subagentStop rewrite replaces the subagent's answer before the parent's task result is built (tg-captures C4a-014), so the post-tool pass then sees token-goat's own output, and compacting and caching it again would store the compacted copy as if it were the report. */
const REWRITTEN_REPORT_RE = /\n\n\[token-goat\] This subagent report \([0-9.]+KB\) is cached for later recall: token-goat mcp-output mcp_[0-9a-f]{16} --full(?:\ntoken-goat: [^\n]*)*$/
/** The compacted report and whether it pays for `notice`. Fence collapse, then intra-report cross-fence dedup, then blank-run collapse, judged by ONE combined net-benefit check rather than a gate each: sub-threshold rewrites could each decline alone when their sum would pass, and firing the notice cost more than once would double-charge it. Shared by the post-tool pass and Copilot's subagentStop rewrite so the two cannot drift. */
function planReportCompaction(resultText: string, recallHint: string, notice: string): { final: string; worthwhile: boolean } {
const cfg = loadConfig().agent_report
const collapsed = collapseFencedBlocks(resultText, recallHint, cfg.fence_collapse_min_lines, cfg.fence_collapse_keep_lines)
// Dedup runs AFTER collapse, on collapse's own output -- see dedupeFencedBlocks's comment for why.
const deduped = dedupeFencedBlocks(collapsed, resultText, recallHint)
// Blank-run collapse runs LAST, on the combined output of both -- see collapseBlankRunsInFences's comment for why.
const final = collapseBlankRunsInFences(deduped)
if (final === resultText) return { final, worthwhile: false }
const worthwhile = isRewriteWorthwhile({
originalBytes: Buffer.byteLength(resultText, 'utf-8'),
rewrittenBytes: Buffer.byteLength(final, 'utf-8'),
noticeBytes: Buffer.byteLength(notice, 'utf-8'),
minNetSavingsBytes: resolveMinNetSavingsBytes(),
})
return { final, worthwhile }
}
/** Book the saving of a report rewrite. Measured against the envelope the parent actually receives (notice included), not the rewritten body alone: the notice is part of what is spent to buy the compaction. */
function recordReportCompaction(resultText: string, updatedOutput: string): void {
const savedBytes = Buffer.byteLength(resultText, 'utf-8') - Buffer.byteLength(updatedOutput, 'utf-8')
if (savedBytes > 0) recordStat('agent_report_compact', savedBytes, savedTokensFromBytes(savedBytes))
}
/** The report with its evidence receipt appended, for a Copilot subagent whose report is not compacted. */
function receiptRewrite(resultText: string, receipt: string): HookOutput {
recordStat('agent_receipt', 0, 0, undefined, 'agent')
return emitRewrite(`${resultText}\n\n${receipt}`, 'agent')
}
/** Copilot CLI's subagentStop hook hands over the subagent's final answer as `response`, and a `modifiedResponse` in reply replaces that answer everywhere the parent sees it: the task tool's result and the model request built from it (tg-captures C4a, Copilot CLI 1.0.88). That is the channel the compacted report goes through there. The post-tool rewrite of the task result has never been shown to be honored on Copilot for the task tool (C1b and C6 cover view and the shell tools only). Only a rewrite that pays for its notice is sent; anything less passes, and the post-tool pass handles the report as it does elsewhere. The report is cached only when the rewrite is sent, under an id computed up front, so a report the post-tool pass goes on to cache is not stored twice. */
export async function subagentReportRewriteHandler(event: HookEvent): Promise<HookOutput> {
try {
if (getHarnessName() !== 'copilot_cli' || !event.sessionId) return passOutput()
const raw = event.raw['last_assistant_message']
if (typeof raw !== 'string' || raw === '') return passOutput()
// Redacted at arrival, for the reason postAgentHandler gives.
const redactedReport = redactSecrets(raw)
const resultText = redactedReport.text
// Computed here because this event IS the subagent's stop: Copilot's post-tool pass never sees the child's state key, and the report the rewrite returns is the one the parent reads.
const receipt = await (await loadAgentReceipt()).receiptForStoppedAgent(event, resultText)
const receiptOnly = (): HookOutput => (receipt === null ? passOutput() : receiptRewrite(resultText, receipt))
if (resultText.length < loadConfig().agent_report.min_bytes) return receiptOnly()
// Keyed on the subagent's own id: the payload names no tool call, and agentId is unique per spawn (tg-captures C4a-013).
const toolInput: Record<string, unknown> = { agent_id: event.agentId ?? '' }
const id = mcpOutputId(event.sessionId, mcpHash('task', toolInput))
const recallHint = `token-goat mcp-output ${id} --full`
const notice = reportNotice(resultText, recallHint, receipt ?? '')
const { final, worthwhile } = planReportCompaction(resultText, recallHint, notice)
if (!worthwhile) return receiptOnly()
if (storeMcpOutput(event.sessionId, 'task', toolInput, resultText) !== id) return receiptOnly()
if (redactedReport.count > 0) recordStat('secret_redacted', 0, redactedReport.count, undefined, 'agent')
if (receipt !== null) recordStat('agent_receipt', 0, 0, undefined, 'agent')
const updatedOutput = `${final}\n\n${notice}`
recordReportCompaction(resultText, updatedOutput)
return emitRewrite(updatedOutput, 'agent', undefined, 'counted-elsewhere')
} catch {
return passOutput()
}
}
// A background spawn's result is its launch ack (it echoes the prompt), not a report.
const ASYNC_ACK_TEXT_OPENER = 'Async agent launched successfully.'
// Non-JSON text is not an object, so it returns null here and takes the text fallback in isAsyncAck.
function parseJsonObject(text: string): Record<string, unknown> | null {
try {
const parsed: unknown = JSON.parse(text)
return parsed !== null && typeof parsed === 'object' && !Array.isArray(parsed) ? (parsed as Record<string, unknown>) : null
} catch {
return null
}
}
// A parsed object is judged by its fields, so key order and whitespace cannot matter; plain text is an ack only when it opens with the launch sentence, so a report that quotes the markers is never misread.
function isAsyncAck(resultText: string): boolean {
const trimmed = resultText.trim()
const fields = parseJsonObject(trimmed)
if (fields !== null) return fields['isAsync'] === true && fields['status'] === 'async_launched'
return trimmed.startsWith(ASYNC_ACK_TEXT_OPENER)
}
export async function postAgentHandler(event: HookEvent): Promise<HookOutput> {
try {
if (!isAgentTool(event.toolName) || !event.sessionId) return passOutput()
// Clear this spawn's outstanding-prompt entry so a later, unrelated Agent spawn with similar wording is not incorrectly flagged as a duplicate of a call that has already finished.
const finished = readSpawnBrief(event.toolName, event.toolInput)
if (finished !== null) removeOutstandingAgentSpawn(finished.text)
// Codex's spawn_agent returns the new agent's handle (multi_agents_spec.rs::spawn_agent_output_schema_v1), not the subagent's report, which arrives later through another tool, so there is nothing here to compact or cache.
if (event.toolName === 'spawn_agent') return passOutput()
// Redact BEFORE anything downstream reads the report, so the compacted envelope this handler hands the model and the blob storeMcpOutput() writes to disk are the same sanitized text. They were not: storeMcpOutput redacts its own copy (see mcp_cache.ts), while the rewriteOutput branch below built `updatedOutput` from the raw result -- so a credential a subagent pasted into its report was redacted on disk and raw in the model's context, in text token-goat itself authored. Redacting at the single point the report enters this handler is what keeps every consumer below on one sanitized source instead of each having to remember.
const redactedReport = redactSecrets(extractToolResultText(event.raw))
const resultText = redactedReport.text
// Already rewritten by subagentReportRewriteHandler on Copilot CLI; see REWRITTEN_REPORT_RE.
if (REWRITTEN_REPORT_RE.test(resultText)) return passOutput()
const agentReportCfg = loadConfig().agent_report
// Built before the min_bytes early returns because the advisory is about the SPAWN, not the report: a lane that came back with a two-line answer paid the same unrestricted prefix. On the early-return paths it rides alone as the whole context output; past them it is folded into `notice` below, BEFORE the net-benefit gate prices that notice, so the gate-then-emit-extra accounting trap cannot reappear here.
const receipt = (await loadAgentReceipt()).takeAgentReceipt(event.sessionId, resultText)
if (receipt !== null) recordStat('agent_receipt', 0, 0, undefined, 'agent')
const spawnAdvisory = [buildUnrestrictedSpawnAdvisory(event.toolInput, getCwd(event)), receipt ?? ''].filter((part) => part !== '').join('\n')
if (!resultText || resultText.length < agentReportCfg.min_bytes || isAsyncAck(resultText)) {
return spawnAdvisory === '' ? passOutput() : contextOutput(spawnAdvisory)
}
// A raw tool_use_id is hashed in a namespaced shape, so an input field of the same name cannot take its slot; absent, the input is hashed unchanged and the id stays as it was.
const toolUseId = event.raw['tool_use_id']
const callInput = typeof toolUseId === 'string' && toolUseId !== '' ? { input: event.toolInput, tool_use_id: toolUseId } : event.toolInput
const id = storeMcpOutput(event.sessionId, event.toolName ?? 'Agent', callInput, resultText)
if (id === null) return spawnAdvisory === '' ? passOutput() : contextOutput(spawnAdvisory)
// Recorded here rather than at the redaction above, and here rather than inside either branch below, because this is the first point past which the redacted report is guaranteed to reach someone: it is now in the cache, and both remaining returns (the compacted rewrite and the annotate-only notice) hand back or point at that same sanitized text. Recording at the redaction itself would credit the early `min_bytes` return, where the raw report reaches the model untouched. `storeMcpOutput`'s own redaction pass finds nothing left to strip now that the text arrives clean, so its disk_cache stat reports zero -- this replaces that count rather than double-counting it.
if (redactedReport.count > 0) recordStat('secret_redacted', 0, redactedReport.count, undefined, 'agent')
recordStat('session_hint', 0, 0)
// `--full` is load-bearing, not decoration: a bare `mcp-output <id>` render elides its own middle past the default head 30 / tail 80, so pointing at it would promise a full report the CLI cannot produce -- the elided fence middles would be exactly what a bare recall drops again.
const recallHint = `token-goat mcp-output ${id} --full`
const notice = reportNotice(resultText, recallHint, spawnAdvisory)
// Compact the envelope only when the combined rewrite actually pays for the notice it adds, using the same shared net-benefit gate as every other rewrite path (hooks_bashoutput, hooks_taskoutput, bash_runner). A report that is long purely because it is long PROSE rewrites to nothing here and correctly falls through to the annotate-only path below, which is the pre-existing behavior.
const { final, worthwhile } = planReportCompaction(resultText, recallHint, notice)
// On a host that drops a result rewrite the compaction is skipped whole: it would book a saving for bytes delivered unchanged, and the receipt in `notice` would go with the rewrite. The notice goes out as context below instead.
if (final !== resultText && !dropsResultRewrite()) {
if (worthwhile) {
const updatedOutput = `${final}\n\n${notice}`
// The sibling session_hint event above stays at 0/0 because appending a pointer genuinely saves nothing; leaving this branch to be represented by that same zero-valued event is precisely the recordStat desync this codebase has fixed repeatedly, and it would report its single largest new saver as worth nothing.
recordReportCompaction(resultText, updatedOutput)
// 'counted-elsewhere': the `secret_redacted` count for this text is booked above, at the point the redacted report enters the cache, because that one record covers the annotate-only return below as well as this one. Letting emitRewrite count the placeholders again here would book the identical redaction twice.
return emitRewrite(updatedOutput, 'agent', undefined, 'counted-elsewhere')
}
// The gate declined: collapse and/or dedup rewrote something but the net savings did not clear the notice cost. Record this at (0, 0) -- like the sibling session_hint event above -- so hit-rate and near-misses are visible instead of the gate's declines being invisible, without inflating any savings total with a non-saving.
recordStat('agent_report_compact_declined', 0, 0)
} else if (final !== resultText && worthwhile && spawnAdvisory === '') {
// A host that drops the rewrite passed silently here before the receipt existed; with nothing to deliver, the recall pointer for a report that went out unchanged would only cost tokens.
return passOutput()
}
return contextOutput(notice)
} catch {
return passOutput()
}
}