Skip to content

Commit 82c19ec

Browse files
author
Token Goat Test
committed
fix(copilot): wire sessionStart so Copilot CLI is told token-goat exists
sessionStart was the one Copilot event hard-coded to return {} without calling token-goat. The comment justified it by claiming token-goat has no internal session_start handler; hooks_session_start.ts has emitted the command-routing reminder for a long time, and every other harness receives it. Copilot sessions alone were never told the commands exist. sessionStart is also the only channel that lands before the model picks its first read tool, so it is where the reminder has to go. install --copilot now registers it and the shim returns the handler's context as {additionalContext}. Verified live against Copilot CLI 1.0.77 using a canary that appears only in the reminder: with the hook wired, a session answers "131072, boundSymbolBody"; with sessionStart removed and nothing else changed, the same question in the same directory answers ABSENT. An earlier probe that simply asked whether it knew token-goat was discarded as leading -- the model invented plausible commands in both arms. github/copilot-cli#2142 (sessionStart additionalContext discarded) would have made this dead wiring; it was fixed months before 1.0.77, and its companion multi-extension overwrite bug hit runtime extension hooks, not this config-file hooks.json path. Measured 360 ms once per session against Copilot's 60 s timeout, and stdout stays pure JSON on every malformed payload, so the fail-closed deny-all behaviour is unaffected.
1 parent 1f1fabf commit 82c19ec

10 files changed

Lines changed: 116 additions & 37 deletions

‎CHANGELOG.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,11 @@ All notable changes to Token-Goat are documented in this file. Format follows Ke
44

55
## [Unreleased]
66

7+
## [2.6.24] - 2026-08-05
8+
9+
### Fixed
10+
- **Copilot CLI now gets the token-goat routing reminder at session start, so it stops forgetting the commands exist.** Copilot was the only supported harness where `sessionStart` was hard-wired to do nothing. The reason given in the code was that token-goat had no session-start handler — untrue for a long time, and the reason Copilot sessions alone were never told token-goat was available. `install --copilot` now registers `sessionStart` and the shim returns the reminder as `additionalContext`. Verified against Copilot CLI 1.0.77 with a canary that appears only in the reminder: wired, a session answers with it; with the hook removed and nothing else changed, the same question in the same directory answers that it has no such note. The upstream bug that would have made this pointless ([github/copilot-cli#2142](https://github.com/github/copilot-cli/issues/2142), `additionalContext` discarded) was fixed months ago, and its companion multi-extension bug never applied to this config-file hook path. If you installed the Copilot bridge before this release, re-run `token-goat install --copilot` and restart Copilot CLI — it caches hook config at session start. See [src/bridges/copilot_cli.ts](src/bridges/copilot_cli.ts), [src/bridges/copilot_cli_install.ts](src/bridges/copilot_cli_install.ts).
11+
712
## [2.6.23] - 2026-08-05
813

914
### Changed

‎README.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -403,9 +403,9 @@ This writes `.pi/extensions/token-goat.ts` in the current project only. Remove i
403403
token-goat install --copilot
404404
```
405405

406-
The `--copilot` flag patches Claude Code and registers a Copilot CLI hook config: `~/.copilot/hooks/token-goat.json` (a `{ version, hooks }` file registering `preToolUse`, `postToolUse`, `preCompact`, `agentStop`, `subagentStop`, and `userPromptSubmitted`, per Copilot's own [hooks reference](https://docs.github.com/en/copilot/reference/hooks-reference)) plus the shim script it points at, `~/.copilot/hooks/token-goat-shim.js`. Unlike Codex, Copilot's event names and response schema (`permissionDecision`/`modifiedArgs` for `preToolUse`, `modifiedResult`/`additionalContext` for `postToolUse`, `decision`/`reason` for `agentStop`/`subagentStop`) genuinely differ from Claude Code's, so the shim translates rather than passes through.
406+
The `--copilot` flag patches Claude Code and registers a Copilot CLI hook config: `~/.copilot/hooks/token-goat.json` (a `{ version, hooks }` file registering `sessionStart`, `preToolUse`, `postToolUse`, `preCompact`, `agentStop`, `subagentStop`, and `userPromptSubmitted`, per Copilot's own [hooks reference](https://docs.github.com/en/copilot/reference/hooks-reference)) plus the shim script it points at, `~/.copilot/hooks/token-goat-shim.js`. Unlike Codex, Copilot's event names and response schema (`permissionDecision`/`modifiedArgs` for `preToolUse`, `modifiedResult`/`additionalContext` for `postToolUse`, `decision`/`reason` for `agentStop`/`subagentStop`) genuinely differ from Claude Code's, so the shim translates rather than passes through.
407407

408-
What works: **bash output compression and re-read denial** (`preToolUse` returns `modifiedArgs` or `permissionDecision: "deny"`), **image shrinking and post-edit indexing** (`postToolUse` returns `additionalContext`), and **stop-hallucination logging** (`agentStop`/`subagentStop` map a token-goat `deny` onto `decision: "block"`, everything else onto `decision: "allow"`). `preCompact` and `userPromptSubmitted` are notification-only on real Copilot CLI, per its docs: Copilot never reads a response body for either, so token-goat's compaction manifest and prompt-context hints have no surfacing channel there. The shim still calls through for both so token-goat's internal side effects keep running, but nothing gets injected back into the agent. Copilot's built-in tool names (`view`, `edit`, `create`, `bash`/`powershell`, `web_fetch`, `grep`, `glob`, `memory`, and MCP-server calls) are remapped onto token-goat's internal names where a clear match exists (`view`→Read, `edit`→Edit, `create`→Write, `bash`/`powershell`→Bash, `web_fetch`→WebFetch, `grep`→Grep, `glob`→Glob); `memory`, `task`, `ask_user`, and MCP tool calls pass through unmapped and simply no-op.
408+
What works: **the command-routing reminder** (`sessionStart` returns `additionalContext`, so Copilot is told token-goat exists before it picks its first read tool — this is the one channel that lands ahead of that decision), **bash output compression and re-read denial** (`preToolUse` returns `modifiedArgs` or `permissionDecision: "deny"`), **image shrinking and post-edit indexing** (`postToolUse` returns `additionalContext`), and **stop-hallucination logging** (`agentStop`/`subagentStop` map a token-goat `deny` onto `decision: "block"`, everything else onto `decision: "allow"`). `preCompact` and `userPromptSubmitted` are notification-only on real Copilot CLI, per its docs: Copilot never reads a response body for either, so token-goat's compaction manifest and prompt-context hints have no surfacing channel there. The shim still calls through for both so token-goat's internal side effects keep running, but nothing gets injected back into the agent. Copilot's built-in tool names (`view`, `edit`, `create`, `bash`/`powershell`, `web_fetch`, `grep`, `glob`, `memory`, and MCP-server calls) are remapped onto token-goat's internal names where a clear match exists (`view`→Read, `edit`→Edit, `create`→Write, `bash`/`powershell`→Bash, `web_fetch`→WebFetch, `grep`→Grep, `glob`→Glob); `memory`, `task`, `ask_user`, and MCP tool calls pass through unmapped and simply no-op.
409409

410410
No ambient environment variable documents "this process is running under Copilot CLI" the way Codex/opencode set one, so the shim sets `TOKEN_GOAT_HARNESS_OVERRIDE=copilot_cli` itself before calling `token-goat hook` (same workaround `--pi` uses). Install also writes a token-goat routing block into `~/.copilot/copilot-instructions.md` (the same delimited-block gate written to `~/.claude/CLAUDE.md` and `~/.codex/AGENTS.md`), merged idempotently so any hand-written content outside the markers is preserved byte-for-byte. To install for one project instead of user scope: `token-goat install --copilot --local` (writes `.github/hooks/token-goat.json` and `.github/copilot-instructions.md` in the current project). To remove: `token-goat uninstall --copilot`.
411411

‎package-lock.json‎

Lines changed: 2 additions & 2 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎package.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
{
22
"name": "token-goat",
3-
"version": "2.6.23",
3+
"version": "2.6.24",
44
"description": "Surgical token-reduction companion for Claude Code and other AI coding agents",
55
"type": "module",
66
"main": "./dist/token-goat.mjs",

‎src/bridges/copilot_cli.ts‎

Lines changed: 19 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -70,14 +70,23 @@ const path = require('node:path')
7070
const { pathToFileURL } = require('node:url')
7171
7272
// Copilot event name -> token-goat internal HookEventName (src/types.ts's
73-
// HOOK_EVENTS). Only these six have a token-goat handler; every other real
73+
// HOOK_EVENTS). Only these seven have a token-goat handler; every other real
7474
// Copilot event (sessionEnd, postToolUseFailure, subagentStart,
7575
// errorOccurred, notification, permissionRequest) is left unimplemented
7676
// rather than guessed at, and falls through to the default no-op below.
77-
// 'sessionStart' is handled as a permanent no-op even though it's a real
78-
// Copilot event, because token-goat has no internal session_start handler
79-
// (mirrors PI_EXTENSION_SCRIPT's documented precedent).
77+
// 'sessionStart' was previously a permanent no-op on the stated grounds that
78+
// token-goat has no internal session_start handler. That was simply wrong --
79+
// hooks_session_start.ts has long emitted the command-routing reminder that
80+
// every other harness receives -- and the no-op was the reason Copilot CLI
81+
// sessions alone never got told token-goat exists. It is wired now: verified
82+
// against Copilot CLI 1.0.77 that a hooks.json sessionStart entry returning
83+
// {additionalContext} does reach the model. The github/copilot-cli#2142
84+
// fire-and-forget bug that would have made this dead wiring was fixed in a
85+
// pre-release months before that version, and its companion multi-extension
86+
// hook-overwrite bug never applied here: it hit runtime *extension* hooks,
87+
// while this config-file hooks.json path goes through Copilot's own merge.
8088
const COPILOT_TO_TG_EVENT = {
89+
sessionStart: 'session_start',
8190
preToolUse: 'pre_tool_use',
8291
postToolUse: 'post_tool_use',
8392
preCompact: 'pre_compact',
@@ -189,11 +198,6 @@ async function tryInProcess(entryPath, tgEvent, canonical) {
189198
async function main() {
190199
const copilotEvent = process.argv[2] || ''
191200
192-
if (copilotEvent === 'sessionStart') {
193-
process.stdout.write('{}')
194-
return
195-
}
196-
197201
const tgEvent = COPILOT_TO_TG_EVENT[copilotEvent]
198202
if (!tgEvent) {
199203
process.stdout.write('{}')
@@ -319,7 +323,10 @@ function translate(copilotEvent, resp) {
319323
return {}
320324
}
321325
322-
if (copilotEvent === 'postToolUse') {
326+
if (copilotEvent === 'postToolUse' || copilotEvent === 'sessionStart') {
327+
// Both surface token-goat's context through the same field. sessionStart is
328+
// the one channel that reaches the model before it picks its first read
329+
// tool, so this is where the routing reminder has to land.
323330
const context = extractContext(resp)
324331
if (context) return { additionalContext: context }
325332
return {}
@@ -343,9 +350,8 @@ function translate(copilotEvent, resp) {
343350
// doc that both are notification-only -- Copilot never reads a response
344351
// body for either, so any additionalContext/systemMessage token-goat
345352
// produces has no surfacing channel here. This still routes through the
346-
// token-goat hook call above (unlike sessionStart's early no-op) so the
347-
// internal handler's own side effects keep running; only the response is
348-
// discarded.
353+
// token-goat hook call above so the internal handler's own side effects keep
354+
// running; only the response is discarded.
349355
return {}
350356
}
351357

‎src/bridges/copilot_cli_install.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -40,6 +40,7 @@ export interface CopilotCliScopeOptions {
4040

4141
/** Copilot's own hook event names that this bridge implements (see copilot_cli.ts's COPILOT_TO_TG_EVENT). */
4242
const COPILOT_CLI_HOOK_EVENTS = [
43+
'sessionStart',
4344
'preToolUse',
4445
'postToolUse',
4546
'preCompact',

‎src/bridges_status.ts‎

Lines changed: 9 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -104,17 +104,21 @@ export const BRIDGE_CAPABILITY_MATRIX: readonly BridgeCapabilityRow[] = [
104104
harness: 'copilot_cli',
105105
label: 'Copilot CLI',
106106
sourceFile: 'src/bridges/copilot_cli_install.ts (COPILOT_CLI_HOOK_EVENTS), src/bridges/copilot_cli.ts (COPILOT_TO_TG_EVENT)',
107-
implemented: new Set(['pre_tool_use', 'post_tool_use', 'pre_compact', 'stop', 'subagent_stop', 'user_prompt_submit']),
107+
implemented: new Set([
108+
'session_start',
109+
'pre_tool_use',
110+
'post_tool_use',
111+
'pre_compact',
112+
'stop',
113+
'subagent_stop',
114+
'user_prompt_submit',
115+
]),
108116
reasons: [
109117
{
110118
events: ['notification'],
111119
reason:
112120
"Copilot CLI has a real 'notification' hook event, but copilot_cli.ts's COPILOT_TO_TG_EVENT deliberately leaves it (and sessionEnd/postToolUseFailure/subagentStart/errorOccurred/permissionRequest) unimplemented rather than guessed at",
113121
},
114-
{
115-
events: ['session_start'],
116-
reason: 'COPILOT_TO_TG_EVENT has no session-start mapping wired yet -- left unimplemented rather than guessed at',
117-
},
118122
],
119123
},
120124
{

‎tests/bridges_status.test.ts‎

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -173,9 +173,12 @@ describe('formatBridgesStatus', () => {
173173
expect(text).toMatch(/opencode:.*tool\.execute\.before/)
174174
})
175175

176-
it('shows a 6/8 score for claudecode/copilot_cli, 5/8 for codex/grok/qwen, 3/8 for opencode/gemini/openclaw/pi', () => {
176+
it('shows a 7/8 score for copilot_cli, 6/8 for claudecode, 5/8 for codex/grok/qwen, 3/8 for opencode/gemini/openclaw/pi', () => {
177177
const text = formatBridgesStatus(BRIDGE_CAPABILITY_MATRIX)
178-
for (const harness of ['claudecode', 'copilot_cli']) {
178+
// copilot_cli overtakes claudecode here: it wires session_start (like claudecode) *and*
179+
// stop via its agentStop mapping, which claudecode's settings.json wiring does not.
180+
expect(text).toMatch(/copilot_cli\s+.*\s7\/8/)
181+
for (const harness of ['claudecode']) {
179182
expect(text).toMatch(new RegExp(`${harness}\\s+.*\\s6\\/8`))
180183
}
181184
for (const harness of ['codex', 'grok', 'qwen']) {

‎tests/hook_event_harness_matrix.test.ts‎

Lines changed: 9 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -210,7 +210,15 @@ const EXPECTED_SUPPORTED_EVENTS: Record<HarnessName, HookEventName[]> = {
210210
pi: ['pre_tool_use', 'post_tool_use', 'pre_compact'],
211211
opencode: ['pre_tool_use', 'post_tool_use', 'pre_compact'],
212212
openclaw: ['pre_tool_use', 'post_tool_use', 'pre_compact'],
213-
copilot_cli: ['pre_tool_use', 'post_tool_use', 'pre_compact', 'stop', 'subagent_stop', 'user_prompt_submit'],
213+
copilot_cli: [
214+
'session_start',
215+
'pre_tool_use',
216+
'post_tool_use',
217+
'pre_compact',
218+
'stop',
219+
'subagent_stop',
220+
'user_prompt_submit',
221+
],
214222
generic: [...HOOK_EVENTS],
215223
}
216224

‎tests/install_copilot_cli.test.ts‎

Lines changed: 63 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -56,7 +56,7 @@ afterEach(() => {
5656
})
5757

5858
describe('installCopilotCli (user scope)', () => {
59-
it('writes the shim script and a hooks config registering all six implemented events on a fresh install', () => {
59+
it('writes the shim script and a hooks config registering all seven implemented events on a fresh install', () => {
6060
const result = installCopilotCli()
6161
expect(result.alreadyInstalled).toBe(false)
6262
expect(result.configPath).toBe(copilotCliConfigPath())
@@ -70,7 +70,21 @@ describe('installCopilotCli (user scope)', () => {
7070
hooks: Record<string, Array<{ type: string; command: string }>>
7171
}
7272
expect(config.version).toBe(1)
73+
// Locked to the exact set, not a subset: a silently dropped event (sessionStart was
74+
// missing entirely for months) has to fail here rather than pass a per-event loop.
75+
expect(Object.keys(config.hooks).sort()).toEqual(
76+
[
77+
'sessionStart',
78+
'preToolUse',
79+
'postToolUse',
80+
'preCompact',
81+
'agentStop',
82+
'subagentStop',
83+
'userPromptSubmitted',
84+
].sort(),
85+
)
7386
for (const event of [
87+
'sessionStart',
7488
'preToolUse',
7589
'postToolUse',
7690
'preCompact',
@@ -520,23 +534,61 @@ describe('COPILOT_CLI_HOOK_SCRIPT', () => {
520534
const mapMatch = /COPILOT_TO_TG_EVENT = \{([\s\S]*?)\}/.exec(COPILOT_CLI_HOOK_SCRIPT)
521535
expect(mapMatch).not.toBeNull()
522536
const mapped = [...(mapMatch?.[1] ?? '').matchAll(/:\s*'([^']+)'/g)].map((m) => m[1])
523-
// 6 entries: preToolUse, postToolUse, preCompact, agentStop, subagentStop, userPromptSubmitted.
524-
expect(mapped.length).toBe(6)
537+
// 7 entries: sessionStart, preToolUse, postToolUse, preCompact, agentStop, subagentStop, userPromptSubmitted.
538+
expect(mapped.length).toBe(7)
525539
for (const eventName of mapped) {
526540
expect(HOOK_EVENTS as readonly string[]).toContain(eventName)
527541
}
528542
})
529543

530-
it('no-ops on sessionStart without invoking token-goat at all', () => {
544+
// sessionStart is the only channel that reaches the model before it chooses its first read
545+
// tool, so it is where token-goat's command-routing reminder has to land. It used to be a
546+
// hard-coded early return, justified in a comment by the claim that token-goat had no
547+
// session_start handler -- untrue, and the reason Copilot CLI sessions alone were never told
548+
// token-goat exists. Verified live against Copilot CLI 1.0.77 before wiring: with the hook
549+
// registered, a session asked for a canary that appears only in the reminder answered
550+
// "131072, boundSymbolBody"; with sessionStart removed and nothing else changed, the same
551+
// question in the same directory answered "ABSENT".
552+
it('forwards sessionStart to the real session_start handler instead of short-circuiting it', () => {
553+
const cwd = mkIsolated()
554+
const { entryPath, capturePath } = writeFakeEntry(cwd)
555+
const scriptPath = path.join(cwd, 'shim.js')
556+
fs.writeFileSync(scriptPath, COPILOT_CLI_HOOK_SCRIPT, 'utf8')
557+
const res = spawnSync(process.execPath, [scriptPath, 'sessionStart', entryPath], {
558+
cwd,
559+
input: JSON.stringify({ sessionId: 's1', cwd: '/tmp' }),
560+
encoding: 'utf8',
561+
timeout: 15000,
562+
env: process.env,
563+
})
564+
expect(res.status).toBe(0)
565+
// The proof the early return is gone: token-goat was actually invoked, with the mapped
566+
// internal event name. A behavioural '{}' assertion could not distinguish "no-op" from
567+
// "invoked and had nothing to say".
568+
expect(fs.existsSync(capturePath)).toBe(true)
569+
expect(JSON.parse(fs.readFileSync(capturePath, 'utf8')) as string[]).toEqual([
570+
'hook',
571+
'session_start',
572+
])
573+
})
574+
575+
it("surfaces the session_start handler's context to Copilot as additionalContext", () => {
576+
const cwd = mkIsolated()
577+
const env = withFakeTokenGoat(
578+
cwd,
579+
JSON.stringify({
580+
hookSpecificOutput: { hookEventName: 'SessionStart', additionalContext: 'ROUTING GATE' },
581+
}),
582+
)
583+
const stdout = runShim('sessionStart', JSON.stringify({ sessionId: 's1', cwd }), cwd, env)
584+
expect(JSON.parse(stdout) as Record<string, unknown>).toEqual({ additionalContext: 'ROUTING GATE' })
585+
})
586+
587+
it('still emits {} for sessionStart when the handler produces no context, rather than a stray key', () => {
531588
const cwd = mkIsolated()
532-
// No fake token-goat on PATH -- if the shim tried to spawn it, spawnSync
533-
// would fail and the shim's own catch-all would still print '{}', so this
534-
// alone wouldn't prove non-invocation. The real proof is the immediate,
535-
// synchronous early-return in the source (checked below) plus this
536-
// behavioral smoke test.
537-
const stdout = runShim('sessionStart', '{}', cwd)
589+
const env = withFakeTokenGoat(cwd, '{}')
590+
const stdout = runShim('sessionStart', JSON.stringify({ sessionId: 's1', cwd }), cwd, env)
538591
expect(stdout.trim()).toBe('{}')
539-
expect(COPILOT_CLI_HOOK_SCRIPT).toMatch(/copilotEvent === 'sessionStart'/)
540592
})
541593

542594
it('no-ops on an event name it does not implement', () => {

0 commit comments

Comments
 (0)