kira-glasses-bridge 2.24.0 → 2.26.0

package/README.md

@@ -4,7 +4,7 @@ Connects your Mac to **Kira**, the assistant for Even Realities G2 glasses. With
 
 ## Setup
 
-1. In the Kira portal, open **Connections → Claude Code → Set up** and copy the command it shows.
+1. In the Kira portal, open **Settings → Devices** and choose **Set up with Terminal**, then copy the command it shows.
 2. Paste it into Terminal:
 
    ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kira-glasses-bridge",
-  "version": "2.24.0",
+  "version": "2.26.0",
   "description": "Connects your Mac to Kira, the assistant for Even G2 glasses: Claude Code sessions, files, folders and apps, by voice.",
   "type": "module",
   "bin": {

package/src/agent-files.mjs

@@ -12,6 +12,7 @@ import {
   exists,
   field,
   inside,
+  oneAtATime,
   readSmall,
   refuseLinks,
   splitFront,
@@ -19,8 +20,13 @@ import {
 } from './config-folders.mjs'
 
 const MAX_MD = 256 * 1024
-/** Claude Code loads the first 200 lines or 25KB of MEMORY.md; Kira keeps it to this. */
+/** A MEMORY.md Kira reads or replaces whole (from the agent's editor) is at most this. */
 const MAX_MEMORY = 64 * 1024
+/** Claude Code loads the first 200 lines or 25KB of MEMORY.md: what Kira adds stays inside that. */
+const LOAD_LINES = 200
+const LOAD_BYTES = 25 * 1024
+/** A line Kira added after a task (rememberAgent): "- 2026-10-12: …". The only lines she ever drops. */
+const KIRAS_LINE = /^- \d{4}-\d{2}-\d{2}: /
 const WHAT = 'a subagent'
 const NAMED = { loose: true }
 const claudeRoot = () => agentFolders()[0].root
@@ -113,19 +119,45 @@ export async function removeAgent({ slug } = {}, root = claudeRoot()) {
 /** Replace a subagent's MEMORY.md, whole (`name` is its front-matter name). */
 export async function writeAgentMemory({ name, md } = {}, root = FOLDERS.claude.agentMemory()) {
   const file = memoryFile(name, root)
-  const text = String(md ?? '')
+  return oneAtATime(file, () => writeMemoryFile(name, file, String(md ?? ''), root))
+}
+
+async function writeMemoryFile(name, file, text, root) {
   if (Buffer.byteLength(text) > MAX_MEMORY) throw new Error('That memory is too large')
   await refuseLinks([root, join(file, '..'), file], 'edit')
   await writeWhole(file, text)
   return { name, path: display(file), memory: text }
 }
 
-/** Add a line to a subagent's MEMORY.md (what Kira keeps after a task); the oldest go when it's full. */
+/**
+ * MEMORY.md with `entry` added at the end, kept inside what Claude Code loads (200 lines, 25KB) by
+ * dropping Kira's own oldest dated lines, never the person's. Null when it can't fit without
+ * dropping theirs (then it isn't added: past the window Claude Code wouldn't read it anyway).
+ */
+export function withEntry(text, entry) {
+  const lines = text.trimEnd() ? text.trimEnd().split('\n') : []
+  lines.push(entry)
+  const fits = () => lines.length <= LOAD_LINES && Buffer.byteLength(`${lines.join('\n')}\n`) <= LOAD_BYTES
+  while (!fits()) {
+    const oldest = lines.findIndex((l, i) => i < lines.length - 1 && KIRAS_LINE.test(l))
+    if (oldest < 0) return null
+    lines.splice(oldest, 1)
+  }
+  return `${lines.join('\n')}\n`
+}
+
+/** Add a line to a subagent's MEMORY.md (what Kira keeps after a task); see withEntry. */
 export async function rememberAgent({ name, line } = {}, root = FOLDERS.claude.agentMemory()) {
+  const file = memoryFile(name, root)
   const entry = `- ${String(line ?? '').replace(/\s+/g, ' ').trim().slice(0, 400)}`
-  let text = `${(await readMemory(name, root)).trimEnd()}\n${entry}`.trim() + '\n'
-  while (Buffer.byteLength(text) > MAX_MEMORY && text.includes('\n')) text = text.slice(text.indexOf('\n') + 1)
-  return writeAgentMemory({ name, md: text }, root)
+  return oneAtATime(file, async () => {
+    const was = await readSmall(file, MAX_MEMORY)
+    // One there that's too big to read is theirs, whole: left as it is.
+    if (was === null && (await exists(file))) return { name, path: display(file), memory: null, full: true }
+    const text = withEntry(was ?? '', entry)
+    if (text === null) return { name, path: display(file), memory: was, full: true }
+    return writeMemoryFile(name, file, text, root)
+  })
 }
 
 /** The bridge tools (index.mjs). */

package/src/agents/checks.mjs

@@ -0,0 +1,61 @@
+// Kira decides each tool call a job's agent wants to make: the bridge asks the API (job.check), which
+// answers from the person's rules (Settings › Permissions) with allow, ask, deny, or mode: no rule
+// decided, so Claude Code's own permission mode does. An API too old to check never says it does,
+// and its jobs are left to Claude Code's mode (asking before edits, settings.mjs); one that checks
+// but can't be reached refuses.
+import { homedir } from 'node:os'
+
+const CHECK_TIMEOUT_MS = 30_000
+const RESEND_MS = 1000
+const MODE = { effect: 'mode', why: null, rule: null, suggest: '' }
+/** What a call is checked on; the rest (a file's whole new text) stays on the Mac. */
+const FIELDS = ['command', 'file_path', 'notebook_path', 'path', 'pattern', 'url', 'query', 'subagent_type']
+
+let checking = false
+let seq = 0
+
+/** Waiting checks by id: the message, to send again after a reconnect, and who's waiting. */
+const waits = new Map()
+
+/** The API said hello: whether it decides tool calls. A check sent just before a disconnect is sent again. */
+export function kiraChecks(on, send) {
+  checking = !!on
+  if (checking) for (const w of waits.values()) send(w.msg)
+}
+
+/** Whether Kira decides each tool call (else Claude Code's mode does, asking before edits). */
+export const kiraDecides = () => checking
+
+/**
+ * Ask Kira about one call. `send` delivers a message now and says whether it could; while the
+ * connection is down (an API deploy) it's tried again until the answer is overdue.
+ */
+export function checkCall(jobId, { tool, input, cwd }, send) {
+  if (!checking) return Promise.resolve(MODE)
+  const id = `c${++seq}-${Date.now().toString(36)}`
+  const fields = Object.fromEntries(FIELDS.filter(f => typeof input?.[f] === 'string').map(f => [f, input[f]]))
+  const msg = { type: 'job.check', jobId, id, call: { tool, input: fields, cwd, home: homedir() } }
+  return new Promise(resolve => {
+    let resend = null
+    const done = decision => {
+      clearTimeout(timer)
+      clearTimeout(resend)
+      waits.delete(id)
+      resolve(decision)
+    }
+    const unreachable = { effect: 'deny', why: 'Kira could not be reached to check this, so it was not run.' }
+    const timer = setTimeout(() => done({ ...unreachable, rule: null, suggest: '' }), CHECK_TIMEOUT_MS)
+    timer.unref?.()
+    waits.set(id, { msg, done })
+    const attempt = () => {
+      if (!send(msg)) resend = setTimeout(attempt, RESEND_MS)
+    }
+    attempt()
+  })
+}
+
+/** Kira's answer to a check. */
+export function decided(msg) {
+  const done = waits.get(String(msg.id))?.done
+  if (done) done({ effect: msg.effect, why: msg.why ?? null, rule: msg.rule ?? null, suggest: msg.suggest ?? '' })
+}

package/src/agents/claude-calls.mjs

@@ -0,0 +1,150 @@
+// Claude Code's tool calls in Kira's agent protocol (protocol.mjs): each one as an action the job
+// shows, as a request when a person has to decide, and the person's answer back as what the Agent
+// SDK expects.
+import { homedir } from 'node:os'
+import { relative, resolve, sep } from 'node:path'
+import { PLAN_OPTIONS, permissionOptions, requestId } from './protocol.mjs'
+
+/** What an agent is told when it may not do something. */
+export const NOT_ANOTHER_WAY =
+  'Do not achieve the same effect another way; if the task cannot proceed without it, ' +
+  'stop and say what you could not do.'
+
+export const TEXT_CAP = 4000
+const DIFF_CAP = 6000
+
+export const short = (s, n = 160) => (String(s ?? '').length > n ? `${String(s).slice(0, n)}…` : String(s ?? ''))
+
+export function displayPath(p, cwd) {
+  if (!p) return ''
+  const rel = relative(cwd, resolve(cwd, p))
+  if (rel && !rel.startsWith('..') && !rel.startsWith(sep)) return rel
+  const home = relative(homedir(), resolve(cwd, p))
+  return home && !home.startsWith('..') ? `~/${home}` : p
+}
+
+/** Claude's tool call as a protocol action. */
+export function describeAction(name, input, cwd) {
+  const i = input ?? {}
+  const act = (type, label, target, more = {}) => ({ type, label, target, ...more })
+  const path = p => displayPath(p, cwd)
+  const cut = (old, now, n) => ({ old: short(old, n), new: short(now, n) })
+  switch (name) {
+    case 'Read':
+      return act('read', 'Read', path(i.file_path))
+    case 'Glob':
+      return act('search', 'Find', i.pattern)
+    case 'Grep':
+      return act('search', 'Search', `${i.pattern}${i.path ? ` in ${path(i.path)}` : ''}`)
+    case 'LS':
+      return act('read', 'List', path(i.path) || '.')
+    case 'Edit': {
+      const edit = { ...cut(i.old_string, i.new_string, DIFF_CAP), all: !!i.replace_all }
+      return act('edit', 'Edit', path(i.file_path), { detail: { edit } })
+    }
+    case 'MultiEdit': {
+      const edits = (i.edits ?? []).slice(0, 20).map(e => cut(e.old_string, e.new_string, 1500))
+      return act('edit', 'Edit', path(i.file_path), { detail: { edits } })
+    }
+    case 'Write':
+      return act('write', 'Write', path(i.file_path), { detail: { content: short(i.content, DIFF_CAP) } })
+    case 'NotebookEdit':
+      return act('edit', 'Edit notebook', path(i.notebook_path))
+    case 'Bash': {
+      const note = i.description ? short(i.description, 120) : undefined
+      return act('run', 'Run', short(i.command, 400), { note, detail: { command: short(i.command, 2000) } })
+    }
+    case 'WebFetch':
+      return act('fetch', 'Fetch', short(i.url, 200))
+    case 'WebSearch':
+      return act('fetch', 'Search the web', short(i.query, 160))
+    case 'Task':
+      return act('delegate', 'Subtask', short(i.description ?? i.prompt, 160))
+    case 'TodoWrite':
+      return act('plan', 'Plan', `${(i.todos ?? []).length} steps`)
+    case 'ExitPlanMode':
+      return act('plan', 'Plan ready', 'asks to go ahead')
+    case 'AskUserQuestion':
+      return act('other', 'Question', short((i.questions ?? []).map(q => q.question).join(' / '), 200))
+    default:
+      return act('other', name, short(JSON.stringify(i), 200))
+  }
+}
+
+/** Claude's tool call as a request, when a person has to decide; `verdict`: what Kira's rules said about it. */
+export function toRequest(name, input, cwd, verdict) {
+  const act = describeAction(name, input, cwd)
+  if (name === 'AskUserQuestion') {
+    const questions = (input.questions ?? []).map((q, n) => ({
+      id: `q${n + 1}`,
+      question: q.question,
+      header: q.header,
+      multi: !!q.multiSelect,
+      options: (q.options ?? []).map((o, k) => ({ id: `o${k + 1}`, label: o.label, description: o.description })),
+    }))
+    const first = questions[0]
+    return {
+      id: requestId(),
+      type: 'choice',
+      title: questions.length === 1 ? first.question : `${questions.length} questions`,
+      options: first?.options ?? [],
+      multi: !!first?.multi,
+      allowText: true,
+      questions,
+      action: { tool: name, label: act.label, target: act.target },
+    }
+  }
+  if (name === 'ExitPlanMode') {
+    return {
+      id: requestId(),
+      type: 'plan',
+      title: 'Claude has a plan and asks to go ahead',
+      detail: short(input.plan ?? '', 6000),
+      options: PLAN_OPTIONS,
+      allowText: true,
+      action: { tool: name, label: act.label, target: act.target },
+    }
+  }
+  const edit = act.detail?.edit
+  const detail = act.detail?.command ?? act.detail?.content ?? (edit ? `- ${edit.old}\n+ ${edit.new}` : undefined)
+  return {
+    id: requestId(),
+    type: 'permission',
+    title: `Claude wants to ${act.label.toLowerCase()} ${act.target}`.trim(),
+    detail: detail ? short(detail, 2000) : undefined,
+    options: permissionOptions(verdict?.suggest),
+    // "No, and tell Claude what to do differently", as Claude Code asks.
+    allowText: true,
+    action: { tool: name, label: act.label, target: act.target },
+    ...(verdict?.suggest ? { rule: verdict.suggest } : {}),
+    ...(verdict?.why ? { why: verdict.why } : {}),
+  }
+}
+
+/** Turn a protocol answer back into what the SDK expects. */
+export function applyAnswer(name, input, request, answer) {
+  const chosen = answer.optionIds ?? []
+  if (request.type === 'choice') {
+    const answers = {}
+    for (const q of request.questions ?? []) {
+      const per = answer.answers?.[q.id]
+      const ids = per?.optionIds ?? (q.id === 'q1' ? chosen : [])
+      const labels = ids.map(id => q.options.find(o => o.id === id)?.label).filter(Boolean)
+      const text = per?.text ?? (q.id === 'q1' ? answer.text : undefined)
+      answers[q.question] = labels.length ? labels.join(', ') : text ?? ''
+    }
+    const filled = Object.values(answers).some(Boolean)
+    const message = 'The user did not answer the question. Stop and say what you need to know.'
+    if (!filled) return { behavior: 'deny', message }
+    return { behavior: 'allow', updatedInput: { ...input, answers, ...(answer.text ? { response: answer.text } : {}) } }
+  }
+  if (request.type === 'plan') {
+    if (chosen.includes('approve')) return { behavior: 'allow', updatedInput: input }
+    const revise = 'The user asked you to revise the plan before going ahead.'
+    return { behavior: 'deny', message: answer.text ? `The user wants the plan changed: ${answer.text}` : revise }
+  }
+  // "Don't ask again" is kept by Kira as a rule of theirs (the request carries it), not by this session.
+  if (chosen.includes('always') || chosen.includes('allow')) return { behavior: 'allow', updatedInput: input }
+  if (answer.text) return { behavior: 'deny', message: `The user said no, and to do this instead: ${answer.text}` }
+  return { behavior: 'deny', message: `The user said no. ${NOT_ANOTHER_WAY}` }
+}

package/src/agents/claude-local.mjs

@@ -1,6 +1,8 @@
-// Claude Code on this Mac, as the person signed in to it: which account it uses, and one piece
-// of text written with that sign-in (complete.mjs). The bridge's calls for both.
+// Claude Code on this Mac, as the person signed in to it: which account it uses, the permission
+// rules in their own settings, and one piece of text written with that sign-in (complete.mjs).
 import { execFile } from 'node:child_process'
+import { readFile } from 'node:fs/promises'
+import { FOLDERS } from '../config-folders.mjs'
 import { completeText } from './complete.mjs'
 
 /** Which Claude account Claude Code on this Mac is signed in to (`claude auth status --json`). */
@@ -26,4 +28,26 @@ async function claudeAccount() {
   )
 }
 
-export const claudeTools = { claude_account: claudeAccount, complete_text: completeText }
+/** The permissions block of a Claude Code settings file, as written there (nothing when it has none). */
+export function permissionsIn(settings) {
+  const p = settings?.permissions ?? {}
+  const rules = v => (Array.isArray(v) ? v.filter(r => typeof r === 'string').slice(0, 200) : [])
+  const defaultMode = typeof p.defaultMode === 'string' ? p.defaultMode : null
+  return { allow: rules(p.allow), ask: rules(p.ask), deny: rules(p.deny), defaultMode }
+}
+
+/** The rules in ~/.claude/settings.json, which Claude Code applies to Kira's jobs as well. */
+async function claudePermissions() {
+  const text = await readFile(FOLDERS.claude.settings(), 'utf8').catch(() => '{}')
+  try {
+    return permissionsIn(JSON.parse(text))
+  } catch {
+    return permissionsIn({})
+  }
+}
+
+export const claudeTools = {
+  claude_account: claudeAccount,
+  claude_permissions: claudePermissions,
+  complete_text: completeText,
+}

package/src/agents/claude.mjs

@@ -1,191 +1,93 @@
 // Claude Code as an agent, through the Agent SDK. Runs in this process on the
 // user's Mac with their own Claude login; files never leave the machine.
 import { query } from '@anthropic-ai/claude-agent-sdk'
-import { homedir } from 'node:os'
-import { relative, resolve, sep } from 'node:path'
-import { PERMISSION_OPTIONS, PLAN_OPTIONS, requestId } from './protocol.mjs'
-import { decide, ruleFor } from './policy.mjs'
-import { policyFor, sdkOptionsFor } from './settings.mjs'
-
-const TEXT_CAP = 4000
-const DIFF_CAP = 6000
-
-const short = (s, n = 160) => (String(s ?? '').length > n ? `${String(s).slice(0, n)}…` : String(s ?? ''))
-
-function displayPath(p, cwd) {
-  if (!p) return ''
-  const rel = relative(cwd, resolve(cwd, p))
-  if (rel && !rel.startsWith('..') && !rel.startsWith(sep)) return rel
-  const home = relative(homedir(), resolve(cwd, p))
-  return home && !home.startsWith('..') ? `~/${home}` : p
-}
-const inside = (cwd, p) => {
-  const rel = relative(cwd, resolve(cwd, String(p ?? '')))
-  return !!rel && !rel.startsWith('..') && !rel.startsWith(sep)
-}
+import { resolve, sep } from 'node:path'
+import {
+  NOT_ANOTHER_WAY,
+  TEXT_CAP,
+  applyAnswer,
+  describeAction,
+  displayPath,
+  short,
+  toRequest,
+} from './claude-calls.mjs'
+import { kiraDecides } from './checks.mjs'
+import { sdkOptionsFor } from './settings.mjs'
 
 /** Kira's MCP server as Claude Code connects to it: Streamable HTTP, the token as the bearer. */
 const kiraServer = ({ url, token }) => ({ type: 'http', url, headers: { Authorization: `Bearer ${token}` } })
 
-/** Claude's tool call as a protocol action. */
-function describeAction(name, input, cwd) {
-  const i = input ?? {}
-  switch (name) {
-    case 'Read':
-      return { type: 'read', label: 'Read', target: displayPath(i.file_path, cwd) }
-    case 'Glob':
-      return { type: 'search', label: 'Find', target: i.pattern }
-    case 'Grep':
-      return { type: 'search', label: 'Search', target: `${i.pattern}${i.path ? ` in ${displayPath(i.path, cwd)}` : ''}` }
-    case 'LS':
-      return { type: 'read', label: 'List', target: displayPath(i.path, cwd) || '.' }
-    case 'Edit':
-      return { type: 'edit', label: 'Edit', target: displayPath(i.file_path, cwd), detail: { edit: { old: short(i.old_string, DIFF_CAP), new: short(i.new_string, DIFF_CAP), all: !!i.replace_all } } }
-    case 'MultiEdit':
-      return { type: 'edit', label: 'Edit', target: displayPath(i.file_path, cwd), detail: { edits: (i.edits ?? []).slice(0, 20).map(e => ({ old: short(e.old_string, 1500), new: short(e.new_string, 1500) })) } }
-    case 'Write':
-      return { type: 'write', label: 'Write', target: displayPath(i.file_path, cwd), detail: { content: short(i.content, DIFF_CAP) } }
-    case 'NotebookEdit':
-      return { type: 'edit', label: 'Edit notebook', target: displayPath(i.notebook_path, cwd) }
-    case 'Bash':
-      return { type: 'run', label: 'Run', target: short(i.command, 400), note: i.description ? short(i.description, 120) : undefined, detail: { command: short(i.command, 2000) } }
-    case 'WebFetch':
-      return { type: 'fetch', label: 'Fetch', target: short(i.url, 200) }
-    case 'WebSearch':
-      return { type: 'fetch', label: 'Search the web', target: short(i.query, 160) }
-    case 'Task':
-      return { type: 'delegate', label: 'Subtask', target: short(i.description ?? i.prompt, 160) }
-    case 'TodoWrite':
-      return { type: 'plan', label: 'Plan', target: `${(i.todos ?? []).length} steps` }
-    case 'ExitPlanMode':
-      return { type: 'plan', label: 'Plan ready', target: 'asks to go ahead' }
-    case 'AskUserQuestion':
-      return { type: 'other', label: 'Question', target: short((i.questions ?? []).map(q => q.question).join(' / '), 200) }
-    default:
-      return { type: 'other', label: name, target: short(JSON.stringify(i), 200) }
-  }
-}
-
-/** Claude's tool call as a request, when a person has to decide. */
-function toRequest(name, input, cwd, suggestions) {
-  const act = describeAction(name, input, cwd)
-  if (name === 'AskUserQuestion') {
-    const questions = (input.questions ?? []).map((q, n) => ({
-      id: `q${n + 1}`,
-      question: q.question,
-      header: q.header,
-      multi: !!q.multiSelect,
-      options: (q.options ?? []).map((o, k) => ({ id: `o${k + 1}`, label: o.label, description: o.description })),
-    }))
-    const first = questions[0]
-    return {
-      id: requestId(),
-      type: 'choice',
-      title: questions.length === 1 ? first.question : `${questions.length} questions`,
-      options: first?.options ?? [],
-      multi: !!first?.multi,
-      allowText: true,
-      questions,
-      action: { tool: name, label: act.label, target: act.target },
-    }
-  }
-  if (name === 'ExitPlanMode') {
-    return { id: requestId(), type: 'plan', title: 'Claude has a plan and asks to go ahead', detail: short(input.plan ?? '', 6000), options: PLAN_OPTIONS, allowText: true, action: { tool: name, label: act.label, target: act.target } }
-  }
-  const detail = act.detail?.command ?? act.detail?.content ?? (act.detail?.edit ? `- ${act.detail.edit.old}\n+ ${act.detail.edit.new}` : undefined)
-  return {
-    id: requestId(),
-    type: 'permission',
-    title: `Claude wants to ${act.label.toLowerCase()} ${act.target}`.trim(),
-    detail: detail ? short(detail, 2000) : undefined,
-    options: PERMISSION_OPTIONS,
-    allowText: false,
-    action: { tool: name, label: act.label, target: act.target },
-  }
-}
-
-/** Turn a protocol answer back into what the SDK expects. */
-function applyAnswer(name, input, request, answer, suggestions) {
-  const chosen = answer.optionIds ?? []
-  if (request.type === 'choice') {
-    const answers = {}
-    for (const q of request.questions ?? []) {
-      const per = answer.answers?.[q.id]
-      const ids = per?.optionIds ?? (q.id === 'q1' ? chosen : [])
-      const labels = ids.map(id => q.options.find(o => o.id === id)?.label).filter(Boolean)
-      const text = per?.text ?? (q.id === 'q1' ? answer.text : undefined)
-      answers[q.question] = labels.length ? labels.join(', ') : text ?? ''
-    }
-    const filled = Object.values(answers).some(Boolean)
-    if (!filled) return { behavior: 'deny', message: 'The user did not answer the question. Stop and say what you need to know.' }
-    return { behavior: 'allow', updatedInput: { ...input, answers, ...(answer.text ? { response: answer.text } : {}) } }
-  }
-  if (request.type === 'plan') {
-    if (chosen.includes('approve')) return { behavior: 'allow', updatedInput: input }
-    return { behavior: 'deny', message: answer.text ? `The user wants the plan changed: ${answer.text}` : 'The user asked you to revise the plan before going ahead.' }
-  }
-  if (chosen.includes('always') || chosen.includes('allow')) return { behavior: 'allow', updatedInput: input, ...(chosen.includes('always') && suggestions?.length ? { updatedPermissions: suggestions } : {}) }
-  return { behavior: 'deny', message: `The user declined this${answer.text ? ` ("${answer.text}")` : ''}. Do not achieve the same effect another way; if the task cannot proceed without it, stop and say what you could not do.` }
-}
-
 /** Claude Code's own prompt, with what Kira adds for this run after it. */
 function systemPromptFor(persona) {
   return { type: 'preset', preset: 'claude_code', ...(persona.systemPrompt ? { append: persona.systemPrompt } : {}) }
 }
 
+/** The pre-tool hook's answer: go ahead, ask, or refuse, and why. */
+const hookAnswer = (permissionDecision, permissionDecisionReason) => ({
+  hookSpecificOutput: { hookEventName: 'PreToolUse', permissionDecision, permissionDecisionReason },
+})
+
+/** Questions for the person, not permissions: they always reach them, whatever the rules say. */
+const QUESTIONS = new Set(['AskUserQuestion', 'ExitPlanMode'])
+
 /**
  * Run one instruction in a Claude session.
  * @param io.emit(event)       a protocol event
  * @param io.ask(request)      resolves to { answer, by } when a person answers (the caller times it out)
+ * @param io.check(call)       what Kira's rules say about a tool call (checks.mjs)
  * @returns { ok, text, error, sessionId, stats }
  */
-/** "Always allow" answers, kept for the rest of the process per session: sessionId -> Set of rules. */
-const sessionRules = new Map()
-
-async function run({ prompt, sessionId, cwd, policy, persona, settings, abort }, io) {
+async function run({ prompt, sessionId, cwd, persona, settings, abort }, io) {
   let session = sessionId ?? null
   let text = ''
   let error = null
-  const rulesFor = () => (session && sessionRules.get(session)) || new Set()
-  // The composer's mode: "Ask" makes the policy ask for edits and commands (settings.mjs).
-  const ruled = policyFor(policy, settings)
-  const judge = (toolName, input) => decide(ruled, toolName, input ?? {}, cwd, rulesFor())
+  /** What Kira's rules said about each tool call, by its id, for the question if Claude Code asks. */
+  const verdicts = new Map()
 
-  // Pre-tool hook: the policy is authoritative. It forces the prompt for what
-  // it does not allow (so a permissive local config cannot bypass the person)
-  // and refuses outright what it denies.
   // A member with a restricted shell (a designer, a researcher) runs only what its preset allows.
   const shellAllow = persona?.shellAllow ? new RegExp(persona.shellAllow) : null
   // A member that only produces artifacts (a designer, a researcher) writes nowhere but its output folders.
   const within = (persona?.writeWithin ?? []).map(d => resolve(cwd, d))
   const writeTools = new Set(['Write', 'Edit', 'MultiEdit', 'NotebookEdit'])
-  const preToolUse = async input => {
+  /** Refused before it runs: the job shows why, and Claude is told (`told`, when it needs more). */
+  const refuse = (tool, reason, told = reason) => {
+    const answer = { optionIds: ['deny'] }
+    io.emit({ kind: 'request_resolved', id: `policy-${Date.now().toString(36)}`, answer, by: 'policy', tool, reason })
+    return hookAnswer('deny', told)
+  }
+  // Pre-tool hook: the member's limits, then Kira's rules (io.check asks the API). Allow and deny
+  // are final; ask forces the question even where the person's own Claude Code settings would allow
+  // it; a call no rule decides is left to Claude Code's permission mode, which asks through canUseTool.
+  const preToolUse = async (input, toolUseID) => {
     if (input.hook_event_name !== 'PreToolUse') return {}
     if (within.length && writeTools.has(input.tool_name)) {
       const target = resolve(cwd, String(input.tool_input?.file_path ?? input.tool_input?.notebook_path ?? ''))
       if (!within.some(dir => target === dir || target.startsWith(dir + sep))) {
-        const reason = `${persona.name} only writes under ${persona.writeWithin.join(', ')}; ${displayPath(target, cwd)} is off limits. Describe what an engineer should change in your spec instead.`
-        io.emit({ kind: 'request_resolved', id: `persona-${Date.now().toString(36)}`, answer: { optionIds: ['deny'] }, by: 'policy', tool: input.tool_name, reason })
-        return { hookSpecificOutput: { hookEventName: 'PreToolUse', permissionDecision: 'deny', permissionDecisionReason: reason } }
+        const where = `${persona.writeWithin.join(', ')}; ${displayPath(target, cwd)} is off limits`
+        const instead = 'Describe what an engineer should change in your spec instead.'
+        return refuse(input.tool_name, `${persona.name} only writes under ${where}. ${instead}`)
       }
     }
     // Every command in a chain ("ls; rm -rf x", "a && b", "a | b") has to be allowed, not only the first.
     const segments = c => String(c ?? '').split(/&&|\|\||;|\|/).map(x => x.trim()).filter(Boolean)
     if (shellAllow && input.tool_name === 'Bash' && !segments(input.tool_input?.command).every(seg => shellAllow.test(seg))) {
-      const reason = `${persona.name} uses the shell only for git and for reading files; run that another way or leave it.`
-      io.emit({ kind: 'request_resolved', id: `persona-${Date.now().toString(36)}`, answer: { optionIds: ['deny'] }, by: 'policy', tool: 'Bash', reason })
-      return { hookSpecificOutput: { hookEventName: 'PreToolUse', permissionDecision: 'deny', permissionDecisionReason: reason } }
+      const only = 'uses the shell only for git and for reading files; run that another way or leave it.'
+      return refuse('Bash', `${persona.name} ${only}`)
     }
-    const { decision, reason } = judge(input.tool_name, input.tool_input)
-    if (decision === 'deny') io.emit({ kind: 'request_resolved', id: `policy-${Date.now().toString(36)}`, answer: { optionIds: ['deny'] }, by: 'policy', tool: input.tool_name, reason })
-    return { hookSpecificOutput: { hookEventName: 'PreToolUse', permissionDecision: decision, permissionDecisionReason: `Kira: ${reason}` } }
+    if (QUESTIONS.has(input.tool_name)) return {}
+    const verdict = await io.check({ tool: input.tool_name, input: input.tool_input ?? {}, cwd })
+    // Kept only for a question that may follow: an ask, or Claude Code's own mode asking.
+    if (toolUseID && (verdict.effect === 'ask' || verdict.effect === 'mode')) verdicts.set(toolUseID, verdict)
+    if (verdict.effect === 'mode') return {}
+    const reason = `Kira: ${verdict.why ?? 'your rules'}${verdict.rule ? ` (${verdict.rule})` : ''}`
+    if (verdict.effect === 'deny') return refuse(input.tool_name, reason, `${reason}. ${NOT_ANOTHER_WAY}`)
+    return hookAnswer(verdict.effect, reason)
   }
 
-  const canUseTool = async (toolName, input, { signal, suggestions }) => {
-    const { decision, reason } = judge(toolName, input)
-    if (decision === 'allow') return { behavior: 'allow', updatedInput: input }
-    if (decision === 'deny') return { behavior: 'deny', message: `Refused by the user's policy (${reason}). Do not achieve the same effect another way; say what you could not do.` }
-    const request = toRequest(toolName, input, cwd, suggestions)
+  const canUseTool = async (toolName, input, { signal, toolUseID }) => {
+    const verdict = verdicts.get(toolUseID)
+    verdicts.delete(toolUseID)
+    const request = toRequest(toolName, input, cwd, verdict)
     io.emit({ kind: 'request', request })
     let resolved
     try {
@@ -193,13 +95,8 @@ async function run({ prompt, sessionId, cwd, policy, persona, settings, abort },
     } catch (err) {
       resolved = { answer: { optionIds: [], text: err.message }, by: 'timeout' }
     }
-    const rule = ruleFor(toolName, input)
-    io.emit({ kind: 'request_resolved', id: request.id, answer: resolved.answer, by: resolved.by, rule })
-    if ((resolved.answer.optionIds ?? []).includes('always') && session) {
-      if (!sessionRules.has(session)) sessionRules.set(session, new Set())
-      sessionRules.get(session).add(rule)
-    }
-    return applyAnswer(toolName, input, request, resolved.answer, suggestions)
+    io.emit({ kind: 'request_resolved', id: request.id, answer: resolved.answer, by: resolved.by })
+    return applyAnswer(toolName, input, request, resolved.answer)
   }
 
   // Background work (subagents, `run_in_background` shell commands, monitors)
@@ -224,7 +121,7 @@ async function run({ prompt, sessionId, cwd, policy, persona, settings, abort },
         env,
         ...(sessionId ? { resume: sessionId } : {}),
         // The model, effort and permission mode the person chose in the composer (plan mode: plan first).
-        ...sdkOptionsFor(settings),
+        ...sdkOptionsFor(settings, kiraDecides()),
         ...(abort ? { abortController: abort } : {}),
         // A Kira agent runs as its Claude Code subagent (~/.claude/agents/<name>.md, agent-files.mjs): the
         // file's body takes the place of Claude Code's default instructions, and what Kira adds for the

package/src/agents/protocol.mjs

@@ -22,11 +22,17 @@ export function requestId() {
   return `r${++requestSeq}-${Date.now().toString(36)}`
 }
 
-export const PERMISSION_OPTIONS = [
-  { id: 'allow', label: 'Allow', description: 'Let it do this once' },
-  { id: 'always', label: 'Always allow', description: 'Let it do this for the rest of the session' },
-  { id: 'deny', label: 'Deny', description: 'Do not do this' },
-]
+/**
+ * A permission's choices, in Claude Code's words. "Don't ask again" adds `rule` to the person's rules
+ * (Kira keeps it); without one (an API that doesn't check calls) it isn't offered.
+ */
+export function permissionOptions(rule) {
+  return [
+    { id: 'allow', label: 'Yes' },
+    ...(rule ? [{ id: 'always', label: 'Yes, and don’t ask again', description: `Adds ${rule} to your rules` }] : []),
+    { id: 'deny', label: 'No', description: 'Tell Claude what to do differently' },
+  ]
+}
 
 export const PLAN_OPTIONS = [
   { id: 'approve', label: 'Approve', description: 'Go ahead with this plan' },