kira-glasses-bridge 2.15.0 → 2.20.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kira-glasses-bridge",
-  "version": "2.15.0",
+  "version": "2.20.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": {
@@ -14,7 +14,8 @@
     "node": ">=20"
   },
   "scripts": {
-    "start": "node src/cli.mjs run"
+    "start": "node src/cli.mjs run",
+    "test": "node --test test/*.test.mjs"
   },
   "dependencies": {
     "@anthropic-ai/claude-agent-sdk": "^0.3.278",

package/src/agents/answers.mjs

@@ -0,0 +1,43 @@
+// Questions a running job asks a person (an approval, a question for them), waiting for the first
+// answer from any device, keyed `${jobId}:${requestId}`. A wait ends at its answer, after three
+// minutes, or when the job is stopped.
+const ANSWER_TIMEOUT_MS = 3 * 60 * 1000
+const waits = new Map()
+
+/** Wait for the answer to one of a job's requests. */
+export function awaitAnswer(jobId, request, signal) {
+  return new Promise((resolve, reject) => {
+    const key = `${jobId}:${request.id}`
+    const end = () => {
+      clearTimeout(timer)
+      waits.delete(key)
+    }
+    const timer = setTimeout(() => {
+      end()
+      reject(new Error('No answer within 3 minutes'))
+    }, ANSWER_TIMEOUT_MS)
+    timer.unref?.()
+    waits.set(key, answered => {
+      end()
+      resolve(answered)
+    })
+    const stopped = () => {
+      end()
+      reject(new Error('The job was stopped'))
+    }
+    signal?.addEventListener('abort', stopped, { once: true })
+  })
+}
+
+/** An answer arrived: true if a request was waiting for it. */
+export function answer(jobId, requestId, answered) {
+  const resolve = waits.get(`${jobId}:${requestId}`)
+  if (!resolve) return false
+  resolve(answered)
+  return true
+}
+
+/** A job ended: whatever it was still asking is dropped. */
+export function forgetJob(jobId) {
+  for (const key of [...waits.keys()]) if (key.startsWith(`${jobId}:`)) waits.delete(key)
+}

package/src/agents/claude.mjs

@@ -5,6 +5,7 @@ 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
@@ -23,6 +24,9 @@ const inside = (cwd, p) => {
   return !!rel && !rel.startsWith('..') && !rel.startsWith(sep)
 }
 
+/** 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. */
 export function describeAction(name, input, cwd) {
   const i = input ?? {}
@@ -133,12 +137,14 @@ function applyAnswer(name, input, request, answer, suggestions) {
 /** "Always allow" answers, kept for the rest of the process per session: sessionId -> Set of rules. */
 const sessionRules = new Map()
 
-export async function run({ prompt, sessionId, cwd, policy, persona, abort }, io) {
+export async function run({ prompt, sessionId, cwd, policy, persona, settings, abort }, io) {
   let session = sessionId ?? null
   let text = ''
   let error = null
   const rulesFor = () => (session && sessionRules.get(session)) || new Set()
-  const judge = (toolName, input) => decide(policy, toolName, input ?? {}, cwd, rulesFor())
+  // 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())
 
   // 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)
@@ -199,7 +205,9 @@ export async function run({ prompt, sessionId, cwd, policy, persona, abort }, io
   // became the job's final report, and Kira told the user it was still going.
   // With this set, the tool has no background option: subagents run inline and
   // their findings are in the answer.
-  const env = { ...process.env, CLAUDE_CODE_DISABLE_BACKGROUND_TASKS: '1' }
+  // Kira has its own Gmail/Calendar/Drive tools; keep the user's claude.ai connectors out of the
+  // sessions it runs, so there's one pathway for acting on their accounts (Kira's).
+  const env = { ...process.env, CLAUDE_CODE_DISABLE_BACKGROUND_TASKS: '1', ENABLE_CLAUDEAI_MCP_SERVERS: 'false' }
   /** Background tasks the model still managed to start (an older CLI ignoring the flag): tool_use id -> description. */
   const orphans = new Map()
 
@@ -210,14 +218,15 @@ export async function run({ prompt, sessionId, cwd, policy, persona, abort }, io
         cwd,
         env,
         ...(sessionId ? { resume: sessionId } : {}),
-        permissionMode: 'default',
+        // The model, effort and permission mode the person chose in the composer (plan mode: plan first).
+        ...sdkOptionsFor(settings),
         ...(abort ? { abortController: abort } : {}),
         // A team member's soul, skills and conventions ride on top of Claude Code's own prompt; its preset says which tools it does without.
         ...(persona?.systemPrompt ? { systemPrompt: { type: 'preset', preset: 'claude_code', append: persona.systemPrompt } } : {}),
         ...(persona?.disallowedTools?.length ? { disallowedTools: persona.disallowedTools } : {}),
-        // Kira has its own Gmail/Calendar/Drive tools; keep the user's claude.ai connectors out of
-        // the sessions it runs, so there's one pathway for acting on their accounts (Kira's).
-        env: { ...process.env, ENABLE_CLAUDEAI_MCP_SERVERS: 'false' },
+        // Claude as the person's Kira: her tools come from her own MCP server, with a token the API
+        // made for this conversation. Claude Code loads them as it needs them (no tool ceiling).
+        ...(persona?.kiraTools ? { mcpServers: { kira: kiraServer(persona.kiraTools) } } : {}),
         canUseTool,
         hooks: { PreToolUse: [{ hooks: [preToolUse] }] },
         ...(process.env.KIRA_CLAUDE_BIN ? { pathToClaudeCodeExecutable: process.env.KIRA_CLAUDE_BIN } : {}),

package/src/agents/policy.mjs

@@ -7,15 +7,84 @@
 // and every piece has to be safe for the whole command to be safe.
 import { relative, resolve, sep } from 'node:path'
 
-export const READ_ONLY = new Set(['Read', 'Glob', 'Grep', 'LS', 'TodoWrite', 'TodoRead', 'NotebookRead', 'Skill'])
+/**
+ * Tools that only look, or that are Claude Code's own housekeeping (ToolSearch loads the definitions
+ * of tools it has but hasn't used yet; the MCP resource tools read what a server offers).
+ */
+export const READ_ONLY = new Set([
+  'Read',
+  'Glob',
+  'Grep',
+  'LS',
+  'TodoWrite',
+  'TodoRead',
+  'NotebookRead',
+  'Skill',
+  'ToolSearch',
+  'ListMcpResourcesTool',
+  'ReadMcpResourceTool',
+])
+/** A subagent: older Claude Code calls the tool Task, newer Agent. */
+const DELEGATE = new Set(['Task', 'Agent'])
 export const EDITS = new Set(['Edit', 'Write', 'MultiEdit', 'NotebookEdit'])
 export const WEB = new Set(['WebFetch', 'WebSearch'])
+/** Claude Code's name for the tools of Kira's MCP server (mcp__<server>__<tool>). */
+export const KIRA_TOOLS = 'mcp__kira__'
 
-/** Read-only commands: looking, listing, testing, type-checking, building. Nothing that writes, sends or installs. */
-const SAFE_CMD = /^(?:ls|ll|pwd|cat|head|tail|wc|echo|printf|which|type|env|printenv|date|whoami|id|uname|tree|find|fd|grep|rg|ag|awk|cut|tr|sort|uniq|diff|comm|stat|file|du|df|basename|dirname|realpath|readlink|jq|yq|xxd|hexdump|strings|test|\[|true|false|sleep|md5|shasum|sha256sum|md5sum|column|nl|less|more|open -n --args|sed -n|sed -E -n|sed -n -E|git (?:status|diff|log|show|branch|rev-parse|remote|ls-files|ls-tree|blame|describe|stash list|tag|config --get|config -l|cat-file|grep|shortlog|count-objects|reflog)|node (?:-v|--version|-e|-p|--eval|--print)|npm (?:-v|--version|ls|list|view|outdated|why|test|run (?:test|lint|typecheck|check|build|format:check))|pnpm (?:-v|--version|ls|list|why|outdated|test|typecheck|lint|build|run (?:test|lint|typecheck|check|build))|yarn (?:-v|--version|list|test|lint|typecheck|build)|npx (?:tsc|eslint|prettier --check|jest|vitest|playwright test)|tsc|eslint|prettier --check|jest|vitest|cargo (?:check|test|build|fmt --check|clippy|tree|metadata)|go (?:test|build|vet|version|list|env)|python3? (?:-V|--version|-m pytest|-c)|pytest|ruby -v|make (?:test|check|lint|build)|mvn (?:test|compile)|gradle (?:test|build)|swift (?:build|test)|xcodebuild -list|brew (?:list|info|--version)|docker (?:ps|images|version)|gh (?:pr (?:list|view|status|checks)|issue (?:list|view)|run (?:list|view)|repo view|api)|heroku (?:logs|ps|releases|config(?::get)?|apps|info))(?:\s|$)/
+/**
+ * Read-only commands: looking, listing, testing, type-checking, building. Nothing that writes, sends
+ * or installs, nothing that runs code given inline (node -e, python -c, awk), nothing that prints
+ * secrets (heroku config).
+ */
+/** Plain commands that only look. */
+const LOOKERS = [
+  'ls', 'll', 'pwd', 'cat', 'head', 'tail', 'wc', 'echo', 'printf', 'which', 'type', 'env', 'printenv',
+  'date', 'whoami', 'id', 'uname', 'tree', 'find', 'fd', 'grep', 'rg', 'ag', 'cut', 'tr', 'sort', 'uniq',
+  'diff', 'comm', 'stat', 'file', 'du', 'df', 'basename', 'dirname', 'realpath', 'readlink', 'jq', 'yq',
+  'xxd', 'hexdump', 'strings', 'test', '[', 'true', 'false', 'sleep', 'md5', 'shasum', 'sha256sum',
+  'md5sum', 'column', 'nl', 'less', 'more', 'tsc', 'eslint', 'jest', 'vitest', 'pytest',
+]
+/** Tools with their read-only, test and build subcommands. */
+const SUBCOMMANDS = {
+  git: [
+    'status', 'diff', 'log', 'show', 'branch', 'rev-parse', 'remote', 'ls-files', 'ls-tree', 'blame', 'describe',
+    'stash list', 'tag', 'config --get', 'config -l', 'cat-file', 'grep', 'shortlog', 'count-objects', 'reflog',
+  ],
+  node: ['-v', '--version'],
+  npm: ['-v', '--version', 'ls', 'list', 'view', 'outdated', 'why', 'test', 'run test', 'run lint', 'run typecheck',
+    'run check', 'run build', 'run format:check'],
+  pnpm: ['-v', '--version', 'ls', 'list', 'why', 'outdated', 'test', 'typecheck', 'lint', 'build', 'run test',
+    'run lint', 'run typecheck', 'run check', 'run build'],
+  yarn: ['-v', '--version', 'list', 'test', 'lint', 'typecheck', 'build'],
+  npx: ['tsc', 'eslint', 'prettier --check', 'jest', 'vitest', 'playwright test'],
+  prettier: ['--check'],
+  cargo: ['check', 'test', 'build', 'fmt --check', 'clippy', 'tree', 'metadata'],
+  go: ['test', 'build', 'vet', 'version', 'list', 'env'],
+  python: ['-V', '--version', '-m pytest'],
+  python3: ['-V', '--version', '-m pytest'],
+  ruby: ['-v'],
+  make: ['test', 'check', 'lint', 'build'],
+  mvn: ['test', 'compile'],
+  gradle: ['test', 'build'],
+  swift: ['build', 'test'],
+  xcodebuild: ['-list'],
+  brew: ['list', 'info', '--version'],
+  docker: ['ps', 'images', 'version'],
+  gh: ['pr list', 'pr view', 'pr status', 'pr checks', 'issue list', 'issue view', 'run list', 'run view', 'repo view'],
+  heroku: ['logs', 'ps', 'releases', 'apps', 'info'],
+  open: ['-n --args'],
+  sed: ['-n', '-E -n', '-n -E'],
+}
+const escape = w => w.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+const withSubs = Object.entries(SUBCOMMANDS).flatMap(([tool, subs]) => subs.map(sub => `${tool} ${sub}`))
+const SAFE_PHRASES = [...LOOKERS, ...withSubs]
+const SAFE_CMD = new RegExp(`^(?:${SAFE_PHRASES.map(escape).join('|')})(?:\\s|$)`)
 
 /** Redirections that write somewhere other than nowhere. */
 const WRITES = /(^|[^&\d])>(?!&)|>>|\btee\b|\bxargs\b|\beval\b|\bexec\b|`/
+/** find and fd can run or delete what they find: then they aren't looking any more. */
+const FINDER_ACTS =
+  /^(?:find|fd)\b.*\s(?:-exec(?:dir)?|-ok(?:dir)?|-delete|-fprint\w*|-fls|-x|--exec(?:-batch)?|-X)\b/
 
 function pieces(command) {
   // Strip quoted strings so separators inside them do not split; keep a placeholder.
@@ -56,7 +125,8 @@ export function shellIsSafe(command, allowRules = []) {
     c = c.slice(0, m.index) + '""' + c.slice(m.index + m[0].length)
   }
   if (WRITES.test(c.replace(/2>&1|2>\/dev\/null|>\/dev\/null|&>\/dev\/null/g, ''))) return false
-  return pieces(c).every(p => SAFE_CMD.test(p) || allowRules.some(r => r && (p === r || p.startsWith(String(r) + ' '))))
+  const allowedByRule = p => allowRules.some(r => r && (p === r || p.startsWith(String(r) + ' ')))
+  return pieces(c).every(p => (SAFE_CMD.test(p) && !FINDER_ACTS.test(p)) || allowedByRule(p))
 }
 
 /** The rule key an "always allow" answer produces. */
@@ -80,6 +150,9 @@ export function decide(policy, toolName, input, cwd, sessionRules = new Set()) {
   if (matchesRule(p.askRules ?? [], toolName, command)) return { decision: 'ask', reason: 'your policy always asks for this' }
   if (matchesRule([...(p.allowRules ?? []), ...sessionRules], toolName, command)) return { decision: 'allow', reason: 'allowed by your policy' }
   if (READ_ONLY.has(toolName)) return { decision: 'allow', reason: 'read-only' }
+  // Kira's own tools (her MCP server, attached when Claude is the person's Kira): her server asks
+  // for itself when something needs their yes (approvals), so the Mac doesn't ask a second time.
+  if (toolName.startsWith(KIRA_TOOLS)) return { decision: 'allow', reason: 'Kira’s own tool' }
   if (EDITS.has(toolName)) {
     const file = input?.file_path ?? input?.notebook_path
     if (insideFolder(cwd, file)) return { decision: p.edits === 'ask' ? 'ask' : 'allow', reason: 'edit inside the project' }
@@ -91,7 +164,7 @@ export function decide(policy, toolName, input, cwd, sessionRules = new Set()) {
     return { decision: 'ask', reason: 'shell command' }
   }
   if (WEB.has(toolName)) return { decision: p.web === 'ask' ? 'ask' : 'allow', reason: 'web' }
-  if (toolName === 'Task') return { decision: p.delegate === 'ask' ? 'ask' : 'allow', reason: 'subagent' }
+  if (DELEGATE.has(toolName)) return { decision: p.delegate === 'ask' ? 'ask' : 'allow', reason: 'subagent' }
   if (toolName === 'ExitPlanMode') return { decision: p.plan === 'allow' ? 'allow' : 'ask', reason: 'plan approval' }
   return { decision: 'ask', reason: 'unfamiliar tool' }
 }

package/src/agents/settings.mjs

@@ -0,0 +1,23 @@
+// How a job runs, as the person chose it in Kira's composer (genui run-settings.ts): the model,
+// the effort, and the permission mode. Pure: the Agent SDK's options and the policy it judges by.
+//
+//   { model?: string, effort?: 'low'|'medium'|'high', mode?: 'auto'|'ask'|'plan' }
+
+const EFFORTS = new Set(['low', 'medium', 'high'])
+const MODEL = /^claude-[a-z0-9-]{1,60}$/
+
+/** The SDK's query options for these settings (left out when unset, so Claude Code's defaults stand). */
+export function sdkOptionsFor(settings) {
+  const s = settings ?? {}
+  return {
+    permissionMode: s.mode === 'plan' ? 'plan' : 'default',
+    ...(typeof s.model === 'string' && MODEL.test(s.model) ? { model: s.model } : {}),
+    ...(EFFORTS.has(s.effort) ? { effort: s.effort } : {}),
+  }
+}
+
+/** The person's policy for this job: "Ask" asks before every edit and every command. */
+export function policyFor(policy, settings) {
+  const p = policy ?? {}
+  return settings?.mode === 'ask' ? { ...p, edits: 'ask', shell: 'ask' } : p
+}

package/src/git-tools.mjs

@@ -0,0 +1,51 @@
+// The bridge's git tools: worktrees for task attempts, what's in a folder's repository, and its
+// branches and worktrees (what Kira offers after @). Spread into index.mjs's tool table.
+import { resolveCwd } from './claude-run.mjs'
+import { snapshot } from './git.mjs'
+import { gitRefs } from './refs.mjs'
+import {
+  listOutputs,
+  prepareWorktree,
+  pushWorktree,
+  removeWorktree,
+  repoOfFolder,
+  stageFiles,
+  uploadOutputs,
+  worktreeStatus,
+} from './worktrees.mjs'
+
+export const gitTools = {
+  /** A worktree for one task attempt, off the project's checkout of the repo. */
+  prepare_worktree: args => prepareWorktree(args),
+  worktree_status: args => worktreeStatus(args),
+  push_worktree: args => pushWorktree(args),
+  remove_worktree: args => removeWorktree(args),
+  /** A task's reference files, downloaded into the worktree's .kira/files for the agent. */
+  stage_files: args => stageFiles(args),
+  /** What a designer or researcher produced under its output folder, and sending it to Kira's storage. */
+  list_outputs: args => listOutputs(args),
+  upload_outputs: args => uploadOutputs(args),
+
+  /** Which GitHub repo a folder's origin points at (project link enrichment). */
+  async repo_of_folder(args) {
+    return { repo: await repoOfFolder(args.path) }
+  },
+
+  /** Read-only git facts for a folder: repo, branch, head, dirty files. */
+  async git_status(args) {
+    const s = await snapshot(resolveCwd(args.path ?? args.cwd))
+    if (!s) return { error: 'not a git repository' }
+    const head = s.head?.slice(0, 7) ?? null
+    return {
+      cwd: s.cwd,
+      repo: s.repo,
+      branch: s.branch,
+      head,
+      dirty: s.dirty.slice(0, 50),
+      dirty_count: s.dirty.length,
+    }
+  },
+
+  /** A folder's branches (newest first) and where each is checked out: here, or in a worktree. */
+  git_refs: args => gitRefs(resolveCwd(args.path ?? args.cwd)),
+}

package/src/git.mjs

@@ -10,7 +10,7 @@ import { randomUUID } from 'node:crypto'
 const DIFF_CAP = 400 * 1024 // bytes of unified diff kept per change
 const COMMIT_CAP = 20
 
-function git(cwd, args, { ok = [0], env = {} } = {}) {
+export function git(cwd, args, { ok = [0], env = {} } = {}) {
   return new Promise(resolve => {
     execFile('git', args, { cwd, maxBuffer: 16 * 1024 * 1024, env: { ...process.env, GIT_OPTIONAL_LOCKS: '0', ...env } }, (err, stdout) => {
       if (err && !ok.includes(err.code)) return resolve(null)

package/src/index.mjs

@@ -8,18 +8,17 @@ import { snapshot, changesSince, display, setupProjectFolder } from './git.mjs'
 import { resolveCwd, folderExists } from './claude-run.mjs'
 import { agentById, AGENTS } from './agents/index.mjs'
 import { normalizeAnswer } from './agents/protocol.mjs'
+import { answer, awaitAnswer, forgetJob } from './agents/answers.mjs'
 import { openApp, installedApps } from './apps.mjs'
 import { listFiles, readUserFile, createFolder, writeUserFile, trashPath, resolveUserPath } from './files.mjs'
 import { initTerminals, terminalCall, terminalMessage, terminalsOffline } from './terminals.mjs'
-import { prepareWorktree, worktreeStatus, pushWorktree, removeWorktree, repoOfFolder, stageFiles, listOutputs, uploadOutputs } from './worktrees.mjs'
+import { gitTools } from './git-tools.mjs'
 
 import { createRequire } from 'node:module'
 const { version: BRIDGE_VERSION } = createRequire(import.meta.url)('../package.json')
 
 let URL_ = ''
 let TOKEN = ''
-/** Requests waiting on a person: `${jobId}:${requestId}` -> resolve({ answer, by }). */
-const answerWaits = new Map()
 /** Running jobs, by id, so a person can stop one. */
 const running = new Map()
 /**
@@ -35,7 +34,6 @@ function sendLive(obj) {
   if (outbox.length >= OUTBOX_MAX) outbox.shift()
   outbox.push(obj)
 }
-const ANSWER_TIMEOUT_MS = 3 * 60 * 1000
 
 /**
  * How the host hears from the bridge. The CLI passes nothing (logs to stdout, exits when the
@@ -143,40 +141,30 @@ const tools = {
       return { error: `The folder ${display(dir)} does not exist on this Mac. Link the project's real folder in the portal, or clone its repository there first (setup_project_folder); never guess a path.` }
     }
     log(`${agent.id} job=${jobId.slice(0, 8)}${args.persona?.name ? ` as ${args.persona.name}` : ''} session=${args.session_id ?? 'new'} in ${display(dir)}: ${prompt.slice(0, 80)}`)
-    const before = await snapshot(dir).catch(() => null)
     let seq = 0
     const io = {
       emit: event => sendLive({ type: 'job.event', jobId, seq: ++seq, at: new Date().toISOString(), event }),
-      ask: (request, signal) =>
-        new Promise((resolve, reject) => {
-          const key = `${jobId}:${request.id}`
-          const timer = setTimeout(() => {
-            answerWaits.delete(key)
-            reject(new Error('No answer within 3 minutes'))
-          }, ANSWER_TIMEOUT_MS)
-          answerWaits.set(key, resolved => {
-            clearTimeout(timer)
-            resolve(resolved)
-          })
-          signal?.addEventListener('abort', () => {
-            clearTimeout(timer)
-            answerWaits.delete(key)
-            reject(new Error('The job was stopped'))
-          }, { once: true })
-        }),
+      ask: (request, signal) => awaitAnswer(jobId, request, signal),
     }
     const abort = new AbortController()
     running.set(jobId, abort)
-    void agent.run({ prompt, sessionId: args.session_id, cwd: dir, policy: args.policy ?? {}, persona: args.persona ?? null, abort }, io).then(async outcome => {
+    // Started is said at once. The git snapshot (what changed, reported at the end) is taken first but
+    // in the background: in a big repository it takes longer than the API waits for this answer.
+    const before = snapshot(dir).catch(() => null)
+    const persona = args.persona ?? null
+    const settings = args.settings ?? null
+    const job = { prompt, sessionId: args.session_id, cwd: dir, policy: args.policy ?? {}, persona, settings, abort }
+    void before.then(() => agent.run(job, io)).then(async outcome => {
       running.delete(jobId)
-      for (const key of [...answerWaits.keys()]) if (key.startsWith(`${jobId}:`)) answerWaits.delete(key)
+      forgetJob(jobId)
       let change = null
-      if (before) change = await changesSince(before).catch(err => (log(`git after job failed: ${err.message}`), null))
+      const was = await before
+      if (was) change = await changesSince(was).catch(err => (log(`git after job failed: ${err.message}`), null))
       log(`job ${jobId.slice(0, 8)} ${outcome.ok ? 'done' : 'error'}${change ? ` · ${change.stats.files} files +${change.stats.adds} -${change.stats.dels}, ${change.commits.length} commits` : ''}`)
       const result = { session_id: outcome.sessionId, result: outcome.text ?? '', stats: outcome.stats, cwd: display(dir), change, agent: agent.id }
       sendLive({ type: 'job', jobId, status: outcome.ok ? 'done' : 'error', result, error: outcome.error })
     })
-    return { started: true, agent: agent.id, cwd: display(dir), git: before ? { repo: before.repo, branch: before.branch, head: before.head?.slice(0, 7) ?? null } : null }
+    return { started: true, agent: agent.id, cwd: display(dir) }
   },
   /** Stop a running job: the agent is cut off; whatever it committed stays. */
   stop_job(args) {
@@ -223,34 +211,7 @@ end tell`
     return new Promise(resolve => execFile('osascript', ['-e', script], err => resolve(err ? { error: err.message } : { opened: true, cwd: display(dir), command })))
   },
 
-  /** A worktree for one task attempt, off the project's checkout of the repo. */
-  prepare_worktree(args) {
-    return prepareWorktree(args)
-  },
-  worktree_status(args) {
-    return worktreeStatus(args)
-  },
-  push_worktree(args) {
-    return pushWorktree(args)
-  },
-  remove_worktree(args) {
-    return removeWorktree(args)
-  },
-  /** A task's reference files, downloaded into the worktree's .kira/files for the agent. */
-  stage_files(args) {
-    return stageFiles(args)
-  },
-  /** What a designer or researcher produced under its output folder, and sending it to Kira's storage. */
-  list_outputs(args) {
-    return listOutputs(args)
-  },
-  upload_outputs(args) {
-    return uploadOutputs(args)
-  },
-  /** Which GitHub repo a folder's origin points at (project link enrichment). */
-  async repo_of_folder(args) {
-    return { repo: await repoOfFolder(args.path) }
-  },
+  ...gitTools,
 
   /** Which Claude account Claude Code on this Mac is signed in to (`claude auth status --json`). */
   async claude_account() {
@@ -268,12 +229,7 @@ end tell`
     )
   },
 
-  /** Read-only git facts for a folder: repo, branch, head, dirty files. */
-  async git_status(args) {
-    const s = await snapshot(resolveCwd(args.path ?? args.cwd))
-    if (!s) return { error: 'not a git repository' }
-    return { cwd: s.cwd, repo: s.repo, branch: s.branch, head: s.head?.slice(0, 7) ?? null, dirty: s.dirty.slice(0, 50), dirty_count: s.dirty.length }
-  },
+
 }
 
 /**
@@ -329,11 +285,8 @@ function connect() {
       return log(`registered as bridge ${msg.bridgeId} (${Object.keys(tools).length} tools)`)
     }
     if (msg.type === 'job.answer') {
-      const key = `${msg.jobId}:${msg.requestId}`
-      const resolve = answerWaits.get(key)
-      if (resolve) {
-        answerWaits.delete(key)
-        resolve({ answer: normalizeAnswer(msg.answer), by: msg.by ?? 'portal' })
+      const by = msg.by ?? 'portal'
+      if (answer(msg.jobId, msg.requestId, { answer: normalizeAnswer(msg.answer), by })) {
         log(`request ${msg.requestId} for job ${String(msg.jobId).slice(0, 8)} answered by ${msg.by ?? 'portal'}`)
       }
       return

package/src/refs.mjs

@@ -0,0 +1,60 @@
+// A folder's branches and worktrees, read from git: what Kira offers after @ ("@branch main"), so
+// a message can point Claude at a place to work. Read-only; the parsers are pure and tested.
+import { display, git } from './git.mjs'
+
+const BRANCH_FORMAT = '%(refname:short)%09%(HEAD)%09%(committerdate:iso-strict)%09%(contents:subject)'
+const MAX_BRANCHES = 60
+
+/** `git branch --format=…` lines: name, whether it's checked out here, when it last moved, its last commit. */
+export function parseBranches(out) {
+  return String(out ?? '')
+    .split('\n')
+    .filter(Boolean)
+    .map(line => {
+      const [name = '', head = '', at = '', subject = ''] = line.split('\t')
+      return { name, current: head.trim() === '*', at: at || null, subject }
+    })
+    .filter(b => b.name && !b.name.startsWith('('))
+}
+
+/** `git worktree list --porcelain`: each worktree's path, branch (null when detached) and head. */
+export function parseWorktrees(out) {
+  return String(out ?? '')
+    .split('\n\n')
+    .map(block => {
+      const field = key =>
+        block
+          .split('\n')
+          .find(l => l.startsWith(`${key} `))
+          ?.slice(key.length + 1) ?? null
+      const branch = field('branch')
+      return {
+        path: field('worktree'),
+        branch: branch ? branch.replace(/^refs\/heads\//, '') : null,
+        head: field('HEAD'),
+      }
+    })
+    .filter(w => w.path)
+}
+
+/** Branches newest first, each with the worktree it's checked out in (if any). */
+export function joinRefs(branches, worktrees, main) {
+  const where = new Map(worktrees.filter(w => w.branch).map(w => [w.branch, w.path]))
+  return [...branches]
+    .sort((a, b) => (b.current ? 1 : 0) - (a.current ? 1 : 0) || String(b.at).localeCompare(String(a.at)))
+    .slice(0, MAX_BRANCHES)
+    .map(b => {
+      const path = where.get(b.name) ?? null
+      return { ...b, worktree: path && path !== main ? display(path) : null, here: path === main }
+    })
+}
+
+export async function gitRefs(dir) {
+  const main = (await git(dir, ['rev-parse', '--show-toplevel']))?.trim()
+  if (!main) return { error: 'not a git repository' }
+  const [branches, worktrees] = await Promise.all([
+    git(main, ['branch', `--format=${BRANCH_FORMAT}`, '--sort=-committerdate']),
+    git(main, ['worktree', 'list', '--porcelain']),
+  ])
+  return { cwd: display(main), branches: joinRefs(parseBranches(branches), parseWorktrees(worktrees), main) }
+}