Skip to content

Commit 05dca95

Browse files
committed
feat(hooks_read): enhance paging hints with real symbols and diff guidance
1 parent af5da53 commit 05dca95

3 files changed

Lines changed: 54 additions & 8 deletions

File tree

‎SECURITY.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -53,7 +53,7 @@ The failed commands token-goat learns fixes for are kept only as keyed digests,
5353

5454
| What you scan | Command | Result |
5555
| --- | --- | --- |
56-
| this repository | `npm audit` | 2 findings, development only: 1 high, body-parser GHSA-27r3-jxmh-p828; 1 moderate, qs GHSA-6pq8-jhm2-2vcw; see below |
56+
| this repository | `npm audit` | 3 findings, development only: 1 high, body-parser GHSA-27r3-jxmh-p828; 1 moderate, qs GHSA-6pq8-jhm2-2vcw; 1 moderate, @hono/node-server GHSA-rmxm-3fg6-px4f; see below |
5757
| an install without optional packages | `npm install --omit=optional token-goat` then `npm audit --omit=dev --omit=optional` | clean, 2 packages |
5858
| a default install | `npm install token-goat` then `npm audit --omit=dev` | clean, 62 packages |
5959

‎src/hooks_read.ts‎

Lines changed: 8 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -401,7 +401,7 @@ function symbolsMeetingRange(
401401
return found
402402
}
403403

404-
/** Names up to 3 real symbols indexed for `filePath` instead of the bare `::Symbol`/`::SymbolName` placeholder a deny/hint text would otherwise print even when the file has none. When `range` is given (a ranged Read's offset/limit), symbols overlapping those lines are preferred over the file's first few. Falls back to a line-range read (`range` given) or `outline` (whole-file) when the file has no indexed symbols at all, since a bare `::Symbol` read would just fail. When the top pick is a large symbol (see {@link isLargeSymbolSpan}), the hint points at a `grep -C --symbol` slice (or `scope` to confirm the enclosing symbol) instead of naming it for a whole-body read. */
404+
/** Names up to 3 real symbols indexed for `filePath` instead of the bare `::Symbol`/`::SymbolName` placeholder a deny/hint text would otherwise print even when the file has none. It attempts the synchronous stale-index heal before querying so a newly created or edited file does not look symbol-less while the worker is behind. When `range` is given (a ranged Read's offset/limit), symbols overlapping those lines are preferred over the file's first few. Falls back to a line-range read (`range` given) or `outline` (whole-file) when parsing still yields no indexed symbols. When the top pick is a large symbol (see {@link isLargeSymbolSpan}), the hint points at a `grep -C --symbol` slice (or `scope` to confirm the enclosing symbol) instead of naming it for a whole-body read. */
405405
export function realSymbolReadHint(filePath: string, shown: string, range?: { start: number; end: number }): string {
406406
let candidates: { name: string; lineStart: number; lineEnd: number }[]
407407
try {
@@ -1143,6 +1143,9 @@ function preReadHandlerInner(event: HookEvent): HookOutput {
11431143
// Grep's cost/relevance depends on its pattern, not just the directory/file it's scoped to — re-scoping several Greps at the same path with different patterns is a legitimate workflow, so Grep is exempt from the count-based re-read dedup below (unlike a repeated whole-file Read).
11441144
if (event.toolName !== 'Grep' && !isImagePath(normalized) && wasFileReadThisSession(normalized)) {
11451145
const entry = getSessionFileEntry(normalized)
1146+
const editedPagingHint = entry?.wasEdited === true
1147+
? ' Recently edited -- run `git diff HEAD -- ' + quotedArg(shown) + '` or `token-goat changed --symbol` to inspect recent changes.'
1148+
: ''
11461149
// Both counts are epoch-scoped: a read from before the last compaction no longer describes what the model currently holds, so it neither counts toward a deny nor shows in the "N reads" a deny quotes. `fullReads` is whole-file re-reads only -- a file touched by nothing but a few narrow offset/limit/view-range slices has never actually been read in full, so the count-based denies below (which assume every prior touch handed over the whole file) must gate on it, not on `reads`, which a slice bumps too.
11471150
const counts = entry !== undefined ? epochReadCounts(entry) : { reads: 1, fullReads: 0 }
11481151
const reads = Math.max(1, counts.reads)
@@ -1274,6 +1277,7 @@ function preReadHandlerInner(event: HookEvent): HookOutput {
12741277
(isSourceExt ? '' : ' ' + surgicalHint(normalized, basename, lineCountForSurgicalHint(normalized)))
12751278
return denyOutput(
12761279
'Sequential line-range paging detected on ' + readSubject(normalized, hint) + ' (' + (prevRanges.length + 1) + ' slices read). ' + hint +
1280+
editedPagingHint +
12771281
' Inspect structure directly without manual chunk paging. Delegate bounded symbol or code extraction to an explore agent (specifically GPT-6 Luna, else Haiku or equivalent) rather than getting stuck in micro-paging loops. Further Read/view line ranges of this file will be denied.',
12781282
)
12791283
}
@@ -1282,8 +1286,8 @@ function preReadHandlerInner(event: HookEvent): HookOutput {
12821286
lockReadRange(rangeKey, [rangeSpan.start, rangeSpan.end], rangeIdentity)
12831287
recordStat('session_hint', 0, 0)
12841288
return denyOutput(
1285-
'deny: overlapping line-range paging detected. Use `token-goat read ' +
1286-
quotedArg(shown + '::Symbol') + '` for a named symbol or delegate bounded extraction to an explore subagent.',
1289+
'deny: overlapping line-range paging detected. Use ' +
1290+
realSymbolReadHint(normalized, shown, rangeSpan) + ' or delegate bounded extraction to an explore subagent.',
12871291
)
12881292
}
12891293
if (rangeSpan !== undefined && evaluateRangeEvasion({
@@ -1362,7 +1366,7 @@ function preReadHandlerInner(event: HookEvent): HookOutput {
13621366
const isSequentialNote = activeSpan !== undefined && isSequentialPagingChain([...activeRanges, [activeSpan.start, activeSpan.end]], 3)
13631367
const pagingNote = (pagingWindow.isExplicitSlice && activeRanges.length >= 2 && isSequentialNote)
13641368
? ' Sequential line-range paging detected (' + (activeRanges.length + 1) + ' slices read). Prefer `token-goat skeleton ' + quotedArg(shown) + '` or ' +
1365-
realSymbolReadHint(normalized, shown, activeSpan) + ', or delegate bounded extraction to an explore agent (specifically Luna, else Haiku).'
1369+
realSymbolReadHint(normalized, shown, activeSpan) + ', or delegate bounded extraction to an explore agent (specifically Luna, else Haiku).' + editedPagingHint
13661370
: ''
13671371
// A ranged Read whose window touches no line served before, with no whole-file read behind it, hands over lines the model has never seen: the already-read note would be false.
13681372
const windowIsNew = isUnseenWindow(pagingWindow, activeRanges, fullReads)

‎tests/hooks_read_paging_ratchet.test.ts‎

Lines changed: 45 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -4,12 +4,14 @@ import * as path from 'node:path'
44

55
import { afterEach, beforeEach, describe, expect, it } from 'vitest'
66

7-
import { preReadHandler } from '../src/hooks_read.js'
7+
import { closeAllDbs } from '../src/db.js'
8+
import { preReadHandler, realSymbolReadHint } from '../src/hooks_read.js'
89
import { postReadHandler } from '../src/hooks_read_post.js'
10+
import { indexFileSync } from '../src/parser.js'
911
import { normalizePath } from '../src/paths.js'
1012
import { clearModuleCaches } from '../src/reset.js'
1113
import { recordRecentReadRange } from '../src/read_range_evasion.js'
12-
import { recordFileRead } from '../src/session.js'
14+
import { recordFileEdit, recordFileLineRange, recordFileRead } from '../src/session.js'
1315
import { foldPath } from '../src/util.js'
1416
import { makeHookEvent } from './helpers/hook-event.js'
1517

@@ -52,11 +54,14 @@ beforeEach(() => {
5254
})
5355

5456
afterEach(() => {
57+
closeAllDbs()
5558
fs.rmSync(dir, { recursive: true, force: true })
5659
})
5760

5861
describe('read paging ratchets', () => {
59-
it('hard-denies IoU above 60% against any of the last three ranges', () => {
62+
it('uses a real symbol in the overlapping-range deny when available', () => {
63+
fs.writeFileSync(target, Array.from({ length: 60 }, (_, i) => `function fn${i + 1}() {}`).join('\n') + '\n')
64+
indexFileSync(target)
6065
recordFileRead(normalizePath(target))
6166
recordRecentReadRange(foldPath(normalizePath(target)), [10, 19])
6267
recordRecentReadRange(foldPath(normalizePath(target)), [100, 109])
@@ -67,6 +72,43 @@ describe('read paging ratchets', () => {
6772
expect(result.hookType).toBe('deny')
6873
if (result.hookType === 'deny') {
6974
expect(result.message).toContain('overlapping line-range paging detected')
75+
expect(result.message).not.toContain('::Symbol')
76+
expect(result.message).toContain('fn12')
77+
}
78+
})
79+
80+
it('adds a diff hint to sequential paging guidance for a file edited this session', () => {
81+
const normalized = normalizePath(target)
82+
recordFileEdit(normalized)
83+
recordFileRead(normalized, false)
84+
recordFileLineRange(normalized, 1, 10)
85+
recordFileLineRange(normalized, 11, 20)
86+
87+
const result = preReadHandler(event('pre_tool_use', { offset: 21, limit: 10 }))
88+
89+
expect(result.hookType).toBe('context')
90+
if (result.hookType === 'context') {
91+
expect(result.context).toContain('Recently edited')
92+
expect(result.context).toContain('git diff HEAD --')
93+
expect(result.context).toContain('token-goat changed --symbol')
94+
}
95+
})
96+
97+
it('adds a diff hint to the hard sequential-paging denial for a file edited this session', () => {
98+
const normalized = normalizePath(target)
99+
recordFileEdit(normalized)
100+
recordFileRead(normalized, false)
101+
recordFileLineRange(normalized, 1, 10)
102+
recordFileLineRange(normalized, 11, 20)
103+
recordFileLineRange(normalized, 21, 30)
104+
105+
const result = preReadHandler(event('pre_tool_use', { offset: 31, limit: 10 }))
106+
107+
expect(result.hookType).toBe('deny')
108+
if (result.hookType === 'deny') {
109+
expect(result.message).toContain('Sequential line-range paging detected')
110+
expect(result.message).toContain('Recently edited')
111+
expect(result.message).toContain('git diff HEAD --')
70112
}
71113
})
72114

0 commit comments

Comments
 (0)