write-gate

1import { atom, read, update } from 'claude-code'
2import type { EngineInterface, Register } from 'claude-code'
3
4import type { Pending } from '../types'
5import { APPROVE, classify, decide, REJECT } from './gate'
6
7const PANE = 'write-gate'
8const LOG = '.claude/write-gate.log'
9
10const ACCENT = 'yellow'
11const MUTED = 'gray'
12const BAR_BG = 'blackBright'
13
14const pending = atom({ plugin: 'write-gate', key: 'pending' } as const, null)
15
16async function git($: EngineInterface, args: string[]) {
17  const { exitCode, stdout } = await $.process
18    .run(['git', ...args], { cwd: await $.session.cwd(), timeoutMs: 5000 })
19    .catch(() => ({ exitCode: 1, stdout: '' }))
20  return exitCode === 0 ? stdout.trim() : null
21}
22
23// For git push and gh pr: the branch, and the commits no remote has yet.
24async function withGitContext($: EngineInterface, gate: Pending): Promise<Pending> {
25  if (gate.tool !== 'Bash') return gate
26  const branch = (await git($, ['rev-parse', '--abbrev-ref', 'HEAD'])) ?? ''
27  const commits =
28    (await git($, ['log', '--oneline', '@{u}..HEAD'])) ??
29    (await git($, ['log', '--oneline', '-n', '20', 'HEAD', '--not', '--remotes'])) ??
30    ''
31  return { ...gate, target: branch, meta: commits ? `Commits not on the remote:\n${commits}` : '' }
32}
33
34async function audit($: EngineInterface, gate: Pending, outcome: string) {
35  const home = (await $.process.run(['printenv', 'HOME'])).stdout.trim()
36  const line = JSON.stringify({ at: new Date().toISOString(), outcome, ...gate }) + '\n'
37  await $.process.run(['sh', '-c', 'cat >> "$0"', `${home}/${LOG}`], { stdin: line }).catch(() => undefined)
38}
39
40async function ask($: EngineInterface, gate: Pending, isShown: boolean) {
41  // The pane did not fit: put the payload in the transcript (never sent to the model).
42  if (!isShown) $.ui.log([`write-gate · ${gate.action} ${gate.target}`, gate.body, gate.meta].filter(Boolean).join('\n\n'))
43  const where = gate.target ? ` to ${gate.target}` : ''
44  // Reject first, so a default or idle pick never sends anything.
45  const answer = await $.ui.ask(`Send this ${gate.action}${where}? (payload in the write-gate pane)`, {
46    header: 'write-gate',
47    options: [REJECT, APPROVE],
48  })
49  return decide(answer)
50}
51
52export const register: Register = on => {
53  on('tool.call', async ($, e, next) => {
54    const found = classify(e)
55    if (!found) return next(e)
56
57    const gate = await withGitContext($, found)
58    await update($, pending, () => gate)
59    const { isPlaced } = await $.ui
60      .open({ id: PANE, title: `write-gate · ${gate.action}` })
61      .catch(() => ({ isPlaced: false }))
62
63    const decision = await ask($, gate, isPlaced).catch(() => ({ isApproved: false as const, reason: 'no one answered the approval dialog' }))
64    await update($, pending, () => null)
65    void $.ui.close({ id: PANE }).catch(() => undefined)
66    await audit($, gate, decision.isApproved ? 'approved' : `rejected: ${decision.reason}`)
67
68    if (decision.isApproved) return next(e)
69    return { deny: `write-gate held this ${gate.action} for approval and ${decision.reason}. Nothing was sent.` }
70  }).catch(($, e, next) =>
71    // Fail closed: a gate that broke before passing the call on blocks it.
72    next.called ? next(e) : { deny: 'write-gate could not ask for approval, so the write was blocked.' },
73  )
74
75  on('ui.render', { component: 'Pane', requestId: PANE }, async ($, e) => {
76    const { Box, Code, Markdown, Text } = $.ui.resolve(e)
77    const gate = await read($, pending)
78    if (gate === null) return <Text dimColor>Nothing is waiting for approval.</Text>
79
80    const isCommand = gate.tool === 'Bash'
81    return (
82      <Box flexDirection="column">
83        <Box backgroundColor={BAR_BG} paddingX={1} gap={1} width={e.props.bodyColumns}>
84          <Text color={ACCENT} bold>
85            ⏸ {gate.action}
86          </Text>
87          {gate.target && <Text color={MUTED}>→ {gate.target}</Text>}
88        </Box>
89        <Box flexDirection="column" paddingX={1} marginTop={1}>
90          {gate.body === '' ? (
91            <Text dimColor>(no body)</Text>
92          ) : isCommand ? (
93            <Code source={gate.body} language="bash" />
94          ) : (
95            <Markdown text={gate.body.slice(0, 9000)} />
96          )}
97          {gate.meta && (
98            <Box flexDirection="column" marginTop={1}>
99              <Text color={MUTED}>{isCommand ? 'git' : 'other arguments'}</Text>
100              <Code source={gate.meta} language={isCommand ? 'text' : 'json'} />
101            </Box>
102          )}
103        </Box>
104        <Box paddingX={1} marginTop={1}>
105          <Text color={MUTED}>Answer in the dialog: {APPROVE} or {REJECT}</Text>
106        </Box>
107      </Box>
108    )
109  })
110}
111

1import type { Pending } from '../types'
2
3// One-way writes to ticketing and diagram systems, by tool name. The server
4// part of the name varies (atlassian, claude_ai_Atlassian_Rovo, ...), so it
5// is matched loosely and the tool part exactly.
6const ATLASSIAN = new Map(Object.entries({
7  addCommentToJiraIssue: 'Jira comment',
8  addWorklogToJiraIssue: 'Jira worklog',
9  createJiraIssue: 'new Jira issue',
10  editJiraIssue: 'Jira edit',
11  transitionJiraIssue: 'Jira transition',
12  createIssueLink: 'Jira issue link',
13  createConfluencePage: 'new Confluence page',
14  updateConfluencePage: 'Confluence page update',
15  createConfluenceFooterComment: 'Confluence comment',
16  createConfluenceInlineComment: 'Confluence inline comment',
17}))
18
19const LUCID = new Map(Object.entries({
20  post_document_thread_comment: 'Lucid comment',
21  share_document_with_collaborators: 'Lucid share',
22  lucid_create_document_share_link: 'Lucid share link',
23  lucid_update_document: 'Lucid document update',
24}))
25
26const PUSH = /\bgit\b(\s+-[Cc]\s+\S+)*\s+push\b/
27const PR = /\bgh\s+pr\s+(create|merge)\b/
28
29// Keys the engine adds to a tool call's input, never the tool's own.
30const RESERVED = new Set(['tool', 'tool_use_id', 'agentId', 'requestMeta', 'consent', 'cloudId'])
31const TARGET_KEYS = ['issueIdOrKey', 'issueKey', 'pageId', 'parentId', 'spaceId', 'documentId', 'projectKey']
32const BODY_KEYS = ['commentBody', 'body', 'content', 'description', 'text', 'comment', 'message']
33
34function mcpAction(tool: string) {
35  const match = /^mcp__(.+)__([^_].*)$/.exec(tool)
36  if (!match) return null
37  const [, server = '', name = ''] = match
38  if (/atlassian|rovo/i.test(server)) return ATLASSIAN.get(name) ?? null
39  if (/lucid/i.test(server)) return LUCID.get(name) ?? null
40  return null
41}
42
43const show = (value: unknown) => (typeof value === 'string' ? value : JSON.stringify(value, null, 2))
44
45// The write this call would make, or null when the call is not gated.
46export function classify(e: { tool: string; [key: string]: unknown }): Pending | null {
47  if (e.tool === 'Bash') {
48    const command = typeof e.command === 'string' ? e.command : ''
49    const pr = PR.exec(command)
50    const action = pr ? `gh pr ${pr[1]}` : PUSH.test(command) ? 'git push' : null
51    if (!action) return null
52    return { tool: e.tool, action, target: '', body: command, meta: '' }
53  }
54
55  const action = mcpAction(e.tool)
56  if (!action) return null
57
58  const args = Object.fromEntries(Object.entries(e).filter(([key]) => !RESERVED.has(key)))
59  const targetKey = TARGET_KEYS.find(key => args[key] !== undefined)
60  const bodyKey = BODY_KEYS.find(key => args[key] !== undefined)
61  const rest = Object.fromEntries(Object.entries(args).filter(([key]) => key !== bodyKey))
62
63  return {
64    tool: e.tool,
65    action,
66    target: targetKey ? String(args[targetKey]) : '',
67    body: bodyKey ? show(args[bodyKey]) : '',
68    meta: Object.keys(rest).length ? JSON.stringify(rest, null, 2) : '',
69  }
70}
71
72export type Decision = { isApproved: true } | { isApproved: false; reason: string }
73
74export const APPROVE = 'Post it'
75export const REJECT = 'Reject'
76
77// Reads the dialog's answer: only an explicit "Post it" approves. Anything
78// typed under Other rejects and becomes the reason Claude reads.
79export function decide(answer: string): Decision {
80  if (answer === APPROVE) return { isApproved: true }
81  if (answer === REJECT || answer.trim() === '') return { isApproved: false, reason: 'the user rejected it' }
82  return { isApproved: false, reason: `the user said: ${answer}` }
83}
84

1// A write held for the user's approval: what it does, where, and its payload.
2export type Pending = {
3  tool: string
4  action: string
5  target: string
6  // The text that will be posted (comment body, page content, command).
7  body: string
8  // The remaining arguments, as JSON, or extra context such as unpushed commits.
9  meta: string
10}
11
12declare module 'claude-code' {
13  interface PluginState {
14    'write-gate': { pending: Pending | null }
15  }
16}
17