Repository navigation
Expand file tree
/
Copy pathhooks_skill.ts
More file actions
234 lines (211 loc) · 16.5 KB
/
Copy pathhooks_skill.ts
File metadata and controls
234 lines (211 loc) · 16.5 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
import { readFile } from 'node:fs/promises';
import type { HookEvent } from './hook_registry.js';
import { registerHook } from './hook_registry.js';
import type { HookOutput } from './types.js';
import { passOutput, denyOutput, getToolName, getToolInput, getCwd, extractToolResponseField, BODY_FIRST_TOOL_RESPONSE_KEYS } from './hooks_common.js';
import { getHarnessName } from './bridges/registry.js';
import { copilotSkillPath } from './copilot_skill_path.js';
import { loadConfig } from './config.js';
import { recordStat, savedTokensFromBytes } from './stats.js';
import {
storeOutput,
installedSkillPath,
incrementSkillHit,
hasSessionOutput,
sessionOutputBodyBytes,
extractCompactFromMarker,
} from './skill_cache.js';
import { recordSkillVersionSnapshot } from './skill_version_drift.js';
import { PER_FILE_COUNTERFACTUAL_CEILING } from './util.js';
import { extractMarkdownHeadings, formatHeadingTreeParts } from './hints/markdown_hints.js';
import { OUTLINE_MIN_HEADINGS, OUTLINE_MAX_REPLACEMENT_RATIO } from './fold_structure.js';
import { fenceUntrustedFileContent } from './injection_scan.js';
import { hintTarget } from './hint_target.js';
import { displaySafeText } from './paths.js';
import { nameSubject, quotedArg, sentenceStart } from './hint_suggestion_guard.js';
const OVERSIZED_FIRST_LOAD_THRESHOLD_BYTES = 6000;
// Largest compact slice still worth inlining rather than pointing at. Deliberately NOT the oversize gate above: that number answers "is the full body too big to hand over", which is a different question from "is this slice cheaper to inline than to make the agent fetch". Denying never prevents the bytes -- the agent runs `skill-body --compact` and receives the identical slice one turn later, having also paid the deny text, a reasoning turn, and a Bash spawn -- so inlining wins at every size the slice is actually smaller than the body. The cap exists only to stop a degenerate marker (a "compact" slice nearly as large as the body it summarises) from being force-fed; past it, the pointer deny still gives the agent the choice.
const COMPACT_INLINE_MAX_BYTES = 24_000;
/** The `skill-section` heading argument: one the skill body really holds, quoted by quotedArg, else the `"<heading>"` placeholder, double-quoted like the skill name before it so the relay guard reads the whole command as quoted. `body` is the text already read on the cold-load path; the reload deny passes only the path and hintTarget reads a bounded head of it. */
function skillSectionArg(skillPath: string | null, body?: string): string {
if (skillPath === null) return '"<heading>"';
const heading = hintTarget(skillPath, 'section', { content: body });
return heading.real ? quotedArg(heading.name) : '"<heading>"';
}
function extractSkillName(toolInput: Record<string, unknown>): string | null {
const skill = toolInput['skill'] as string;
if (skill && typeof skill === 'string') {
return skill;
}
const command = toolInput['command'] as string;
if (command && typeof command === 'string') {
return command;
}
return null;
}
function extractSkillBody(raw: Record<string, unknown>): string {
return extractToolResponseField(raw, BODY_FIRST_TOOL_RESPONSE_KEYS);
}
/** Copilot CLI's skill tool answers with a one-line confirmation (`Skill "<name>" loaded successfully. Follow the instructions in the skill context.`) and delivers the body separately, as a `<skill-context>` user message the hook never sees (tg-captures C5, Copilot CLI 1.0.88). Its tool result is therefore not the skill, and its skills live in Copilot's own directories rather than Claude Code's. */
function skillResultIsConfirmationOnly(): boolean {
return getHarnessName() === 'copilot_cli';
}
/** The on-disk SKILL.md the running harness loads for `skillName`: Copilot's project and personal skill directories on Copilot CLI, Claude Code's skills directory (or plugin manifest) everywhere else. */
function harnessSkillPath(event: HookEvent, skillName: string): Promise<string | null> {
if (skillResultIsConfirmationOnly()) return copilotSkillPath(skillName, getCwd(event) ?? null);
return installedSkillPath(skillName);
}
/** Shared prologue for {@link preSkillHandler}/{@link postSkillHandler}: only a Skill call with an extractable skill name and a session id is in scope; everything else passes through. */
function resolveSkillContext(event: HookEvent): { skillName: string } | null {
const toolName = getToolName(event);
if (toolName !== 'Skill') {
return null;
}
const toolInput = getToolInput(event);
const skillName = extractSkillName(toolInput);
if (!skillName) {
return null;
}
if (!event.sessionId) {
return null;
}
return { skillName };
}
/** Heading-tree stand-in for an oversized skill body, or null when the body is not worth mapping. Two callers, one floor pair. Both floors come verbatim from fold_structure.ts's large-markdown outline, which measured them against real session transcripts: a skill needs at least OUTLINE_MIN_HEADINGS of structure to be worth a map at all, and the map has to be genuinely small next to the body (OUTLINE_MAX_REPLACEMENT_RATIO) or the round trip costs more than it saves. */
function planHeadingTree(body: string, bodyBytes: number, skillName: string, sourcePath: string): { sectionsList: string; treeBytes: number; phrase: string } | null {
const headings = extractMarkdownHeadings(body);
if (headings.length < OUTLINE_MIN_HEADINGS) return null;
const { sectionsList } = formatHeadingTreeParts(headings, skillName);
const treeBytes = Buffer.byteLength(sectionsList, 'utf-8');
if (treeBytes > bodyBytes * OUTLINE_MAX_REPLACEMENT_RATIO) return null;
// The displayed tree caps at MAX_HEADINGS (40); when the file has more H1-H3 headings than that, the message must say so or the model reads a truncated tree as a complete map and never learns the remaining sections exist. It must also say how to reach them: skill-section resolves any heading in the file, shown or not, so the only thing the model lacks is the names, and `outline` lists every one. An earlier wording sent it to `skill-body` for them, which loads the whole body this deny exists to withhold.
const totalHeadings = extractMarkdownHeadings(body, Number.MAX_SAFE_INTEGER).length;
const phrase = totalHeadings > headings.length
? 'its heading tree shows ' + headings.length + ' of ' + totalHeadings +
' headings below instead of the full body; the other ' + (totalHeadings - headings.length) +
' load by name just the same, and `token-goat outline ' + quotedArg(displaySafeText(sourcePath)) + '` lists all ' + totalHeadings + '.'
: 'its heading tree (' + headings.length + ' headings) is inlined below instead of the full body.';
return { sectionsList, treeBytes, phrase };
}
export async function preSkillHandler(event: HookEvent): Promise<HookOutput> {
try {
const ctx = resolveSkillContext(event);
if (ctx === null) {
return passOutput();
}
const { skillName } = ctx;
// The name comes from the model's tool input (`skill`, or `command` when that is absent), so every suggested command carries it as one quoted argument.
const nameArg = quotedArg(skillName);
const skillSubject = sentenceStart(nameSubject('skill', skillName));
if (!loadConfig().hints.pre_skill_advisory) {
return passOutput();
}
// Skill already loaded earlier this session: its body is cached and recallable, so re-loading just re-injects the whole thing. Deny and point at the cheaper compact recall instead.
if (await hasSessionOutput(event.sessionId, skillName)) {
// The blocked re-load's body never reaches the model -- this is the same shape as read_count_deny's blocked re-read, so credit it the same way: the cached body's real byte size (sessionOutputBodyBytes), capped at PER_FILE_COUNTERFACTUAL_CEILING because the counterfactual being priced is "the load that didn't happen", and that load would itself have been truncated past this ceiling (see PER_FILE_COUNTERFACTUAL_CEILING). No sibling stat credits these same bytes: skill_load (postSkillHandler) is event-only (0 bytes) and only fires on an actual load, which this deny prevents.
const cachedBytes = await sessionOutputBodyBytes(event.sessionId, skillName);
const denyCredit = cachedBytes !== null ? Math.min(cachedBytes, PER_FILE_COUNTERFACTUAL_CEILING) : 0;
recordStat('session_hint', denyCredit, savedTokensFromBytes(denyCredit), undefined, 'skill-reload-deny');
return denyOutput(
skillSubject + ' was already loaded this session and is cached. Use `token-goat skill-section ' +
nameArg + ' ' + skillSectionArg(await harnessSkillPath(event, skillName)) + '` to recall a section, `token-goat skill-body ' +
nameArg + ' --compact` to recall the compact slice, or `token-goat skill-body ' + nameArg +
'` for the full body instead of re-loading it.',
);
}
// First (cold) load of an oversized skill with an extractable compact: gate this too, or the full body still lands in context once per skill per session regardless of repeat-load protection.
const sourcePath = await harnessSkillPath(event, skillName);
if (sourcePath) {
try {
const body = await readFile(sourcePath, 'utf-8');
const bodyBytes = Buffer.byteLength(body, 'utf-8');
if (bodyBytes > OVERSIZED_FIRST_LOAD_THRESHOLD_BYTES) {
const compact = extractCompactFromMarker(body);
if (compact !== null) {
// The compact slice is already in hand here, so denying with a pointer to `skill-body --compact` costs an extra agent turn (reasoning + Bash call + that command's echo) to re-fetch content this handler just computed. Inline it instead whenever it is genuinely smaller than the body and under COMPACT_INLINE_MAX_BYTES. This used to reuse the oversize gate as the inline bound, which put every slice between 6 KB and the body's size on the deny path -- the agent paid the round trip and received exactly the same bytes anyway, which is why that branch's stat shows real traffic and zero savings. With no marker, a slice no smaller than the body, or a read failure, the original pointer deny stands verbatim.
const compactBytes = Buffer.byteLength(compact, 'utf-8');
// At least half the body has to disappear for inlining to beat pointing. "Any saving at all" is too weak a test: a marker placed at the very end makes the slice the whole body minus the marker line, which passes a bare `compactBytes < bodyBytes` while handing over every byte and booking it as a saving. Past that ratio the pointer is the better trade, because the agent may not need the body at all.
if (compactBytes * 2 <= bodyBytes && compactBytes <= COMPACT_INLINE_MAX_BYTES) {
const savedBytes = bodyBytes - compactBytes;
recordStat('skill_compact_inlined', savedBytes, savedTokensFromBytes(savedBytes));
return denyOutput(
skillSubject + ' is large (' + bodyBytes + ' bytes); its compact slice (' + compactBytes +
' bytes) is inlined below instead of the full body. For a specific section, run `token-goat skill-section ' + nameArg +
' ' + skillSectionArg(sourcePath, body) + '`, or `token-goat skill-body ' + nameArg + '` if you need the full body.\n\n' + compact,
);
}
}
// The heading tree serves both arms, and the arm that had been missing it is the larger one. A marker sitting near the end of a file produces a slice too big to inline, and that used to fall to a bare pointer naming `skill-section \'<heading>\'` without ever saying what the headings were -- so recovering cost a listing call the deny had all the information to answer. A skill with a badly-placed marker was strictly worse off than one with no marker at all, which got the map. Same replacement, same floors, whichever arm arrives here.
const tree = planHeadingTree(body, bodyBytes, skillName, sourcePath);
if (tree !== null) {
// Two arms, two counterfactuals, and using the no-marker one for both would over-credit. With no marker the handler falls through to a real load, so the body is genuinely what the tree replaces. With a marker the body was never going to be delivered -- the pointer deny already stopped it -- and the bytes the agent would actually have pulled are the slice that pointer named. Credit that instead. On the skills this fires for the two numbers are within a few percent (a marker sitting near the end makes the slice nearly the whole body), which is exactly why the wrong one would have looked right.
const replaced = compact !== null ? Buffer.byteLength(compact, 'utf-8') : bodyBytes;
const savedBytes = Math.max(0, replaced - tree.treeBytes);
// `marker=` carries the authoring signal the merge would otherwise bury: an unusable slice is a fixable marker placement, a missing one is a skill that never opted in, and both now land under the same kind.
recordStat('skill_heading_tree_inlined', savedBytes, savedTokensFromBytes(savedBytes), undefined, 'skill=' + skillName + ' marker=' + (compact !== null ? 'unusable' : 'none'));
return denyOutput(
skillSubject + ' is large (' + bodyBytes + ' bytes)' +
(compact !== null ? ', and its compact slice is too large to inline; ' : ' with no compact slice; ') + tree.phrase +
' Use `token-goat skill-section ' + nameArg + ' ' + skillSectionArg(sourcePath, body) + '` to load a specific section' +
(compact !== null ? ', `token-goat skill-body ' + nameArg + ' --compact` to load the compact slice' : '') +
', or `token-goat skill-body ' + nameArg + '` for the full body.\n\n' +
fenceUntrustedFileContent(tree.sectionsList),
);
}
if (compact !== null) {
// Too little structure to map and a slice too large to inline: the pointer is all that is left, and it is still better than the whole body. Without a marker this falls through to the normal load instead, exactly as before -- there is nothing to point at.
recordStat('skill_oversized_first_load');
return denyOutput(
skillSubject + ' is large (' + bodyBytes +
' bytes) and has a compact slice available. Use `token-goat skill-section ' + nameArg +
' ' + skillSectionArg(sourcePath, body) + '` to load a specific section, `token-goat skill-body ' + nameArg +
' --compact` to load the compact slice, or `token-goat skill-body ' + nameArg + '` for the full body.',
);
}
}
} catch {
// fail-soft: unreadable file just falls through to the normal load
}
}
return passOutput();
} catch {
return passOutput();
}
}
export async function postSkillHandler(event: HookEvent): Promise<HookOutput> {
try {
const ctx = resolveSkillContext(event);
if (ctx === null) {
return passOutput();
}
const { skillName } = ctx;
recordStat('skill_load');
let body: string;
let sourcePath: string | null;
if (skillResultIsConfirmationOnly()) {
// The tool result is only a confirmation line, so the body is read from the file Copilot loaded. With no such file there is nothing recallable to store, and storing the confirmation would make the next load's deny point at a `skill-body` that cannot find the skill.
sourcePath = await harnessSkillPath(event, skillName);
if (sourcePath === null) {
return passOutput();
}
body = await readFile(sourcePath, 'utf-8');
} else {
body = extractSkillBody(event.raw);
sourcePath = await installedSkillPath(skillName);
}
if (!body) {
return passOutput();
}
// Persist the loaded body under the real skill name (toolInput.skill), so skill-compact/skill-body/skill-list can recall it after compaction. Keyed by skill name + content hash; storeOutput dedups identical bodies across sessions. sourcePath points at the on-disk install when present, so getSkillFilePath resolves it without the disk-scan fallback.
await storeOutput(event.sessionId, skillName, body, sourcePath ? { sourcePath } : undefined);
// Increment hit count for skill recall tracking.
await incrementSkillHit(skillName);
// Stamp this (re)load's CLI version/command set as the session's drift baseline -- see skill_version_drift.ts. No-op unless skillName is 'token-goat' itself.
await recordSkillVersionSnapshot(event.sessionId, skillName);
return passOutput();
} catch {
return passOutput();
}
}
registerHook('pre_tool_use', preSkillHandler, { toolName: 'Skill' });
registerHook('post_tool_use', postSkillHandler, { toolName: 'Skill' });