driver-seat-guard

1import { atom, read, update } from 'claude-code'
2import type { EngineInterface, Register } from 'claude-code'
3
4import type { Guard } from '../types'
5
6const guard = atom({ plugin: 'driver-seat-guard', key: 'guard' } as const, {
7  isOn: false,
8  todo: null,
9  isSearchAsked: false,
10} as Guard)
11
12const TODOS = '.driver-seat/todos'
13const SEARCH_ASK = /\b(search|look (it|this|that) up|google|web|check the docs)\b/i
14
15const PACING = (todo: string | null) => `# Driver-seat learn mode (enforced by a plugin)
16The user writes the code. You tutor.
17- Give ONLY the next single step: 3-6 sentences, one tiny concrete example.
18- Do not explain later steps, write tests for later todos, or start workers.
19- If the user says they don't understand, answer simpler and shorter, not reworded.
20- Web search/fetch is blocked unless the user's latest prompt asks for it.
21${todo ? `- Active todo: ${todo}. Stay inside it until the user says to move on.` : '- No active todo set.'}`
22
23// Finds the NNN of the todo whose frontmatter says `status: doing`.
24async function doingTodo($: EngineInterface): Promise<string | null> {
25  const entries = await $.fs.list(TODOS).catch(() => [])
26  for (const entry of entries) {
27    if (entry.kind !== 'file' || !entry.name.endsWith('.md')) continue
28    const text = await $.fs.read(`${TODOS}/${entry.name}`).catch(() => '')
29    if (typeof text === 'string' && /^status:\s*doing\b/m.test(text)) {
30      return entry.name.match(/^\d+/)?.[0] ?? null
31    }
32  }
33  return null
34}
35
36// True when `path` belongs to a todo other than `active` (e.g. a red test for 003
37// while 001 is in progress). Return false to allow the write.
38export function isOffTodo(path: string, active: string): boolean {
39  // TODO(driver): your rule. See the request in chat.
40  return false
41}
42
43export const register: Register = on => {
44  on('session.start', async ($, e, next) => {
45    await $.command.register({
46      name: 'learn',
47      description: 'Learn mode: /learn [todo NNN] on, /learn off',
48    })
49    return next(e)
50  })
51
52  on('command.run', { command: 'learn' }, async ($, e) => {
53    const arg = e.args.trim()
54    if (arg === 'off') {
55      await update($, guard, g => ({ ...g, isOn: false }))
56      return { text: 'Learn mode off.' }
57    }
58    const todo = arg.match(/^\d+$/) ? arg : await doingTodo($)
59    await update($, guard, g => ({ ...g, isOn: true, todo }))
60    return { text: `Learn mode on. Active todo: ${todo ?? 'none (pass /learn NNN)'}.` }
61  })
62
63  on('prompt.submit', async ($, e, next) => {
64    await update($, guard, g => ({ ...g, isSearchAsked: SEARCH_ASK.test(e.text) }))
65    return next(e)
66  })
67
68  on('prompt.compose', async ($, e, next) => {
69    const composed = await next(e)
70    const g = await read($, guard)
71    if (!g.isOn) return composed
72    return {
73      sections: [
74        ...composed.sections,
75        { id: 'driver-seat-guard:pacing', text: PACING(g.todo), scope: 'session' as const },
76      ],
77    }
78  })
79
80  on('tool.call', { tool: ['WebSearch', 'WebFetch'] }, async ($, e, next) => {
81    const g = await read($, guard)
82    return g.isOn && !g.isSearchAsked
83      ? { deny: `driver-seat-guard: learn mode, no ${e.tool} unless the user asks for a search.` }
84      : next(e)
85  }).catch(($, e, next) => (next.called ? next(e) : { deny: 'driver-seat-guard: guard failed.' }))
86
87  on('tool.call', { tool: ['Write', 'Edit'] }, async ($, e, next) => {
88    const g = await read($, guard)
89    return g.isOn && g.todo && isOffTodo(e.file_path, g.todo)
90      ? { deny: `driver-seat-guard: ${e.file_path} belongs to a later todo; active is ${g.todo}.` }
91      : next(e)
92  }).catch(($, e, next) => (next.called ? next(e) : { deny: 'driver-seat-guard: guard failed.' }))
93
94  on('ui.render', { component: 'AbovePrompt' }, async ($, e, next) => {
95    const g = await read($, guard)
96    if (!g.isOn || e.props.hasSurvey) return next(e)
97    const { Box, Text } = $.ui.resolve(e)
98    return (
99      <Box flexDirection="column">
100        <Text dimColor>LEARN · todo {g.todo ?? 'none'} · /learn off to exit</Text>
101        {await next(e)}
102      </Box>
103    )
104  })
105}
106

1export type Guard = { isOn: boolean; todo: string | null; isSearchAsked: boolean }
2
3declare module 'claude-code' {
4  interface PluginState {
5    'driver-seat-guard': { guard: Guard }
6  }
7}
8