fix(orchestration): claim a terminal answer only from what Claude shows

An answer is written only while a caught-up screen still shows the dialog
in the same process run, and claimed only once Claude shows it applied: the
hook's deny line for a deny, no other close for an allow. A Yes, a No or the
2:00 auto-block that wins the race is refused and named from the screen.

A hook that hangs up is not an answer: with the dialog still up the
coordinator is told a person must answer it in the worker's terminal.

A PermissionRequest entry the user made async stays async: it prints {}
first and never waits for a decision.
This commit is contained in:
Jinwoo-H
2026-11-11 03:39:43 -05:00
parent bb12d3e90c
commit a4f4e7a4e6
13 changed files with 366 additions and 150 deletions
@@ -0,0 +1,35 @@
import {
MANAGED_HOOK_TIMEOUT_SECONDS,
type HookCommandConfig
} from '../agent-hooks/installation/configuration/hook-config-schema'
// Read by the hook script: this entry runs async, so Claude ignores its output and nothing waits on it.
const ASYNC_FLAG = 'export ORCA_HOOK_ASYNC=1; '
/** A managed PermissionRequest entry the user made async prints `{}` first, never waits for an
* answer, and keeps the shared timeout. Only POSIX commands can carry the flag. */
export function withClaudeAsyncPermissionRequest(
eventName: string,
hook: HookCommandConfig,
posixCommand: boolean
): HookCommandConfig {
return eventName === 'PermissionRequest' && hook.async === true && posixCommand
? asyncForm(hook)
: hook
}
/** The installed forms an event may take; async ones are appended so an index still names its launcher. */
export function claudeManagedHookForms(
eventName: string,
forms: HookCommandConfig[]
): HookCommandConfig[] {
return eventName === 'PermissionRequest' ? [...forms, ...forms.map(asyncForm)] : forms
}
function asyncForm(hook: HookCommandConfig): HookCommandConfig {
return {
...hook,
command: `${ASYNC_FLAG}${hook.command}`,
timeout: MANAGED_HOOK_TIMEOUT_SECONDS
}
}
@@ -127,6 +127,15 @@ describe.skipIf(process.platform === 'win32')(
expect(await runHook(ASK, { ORCA_AGENT_HOOK_PORT: String(wrong.port) })).toBe('{}\n')
})
it('answers {} first and asks for no decision when the user made PermissionRequest async', async () => {
const { port, seen } = await hookServer(() => PERMISSION_DENY)
expect(await runHook(ASK, { ORCA_AGENT_HOOK_PORT: String(port), ORCA_HOOK_ASYNC: '1' })).toBe(
'{}\n'
)
expect(seen).toHaveLength(1)
expect(seen[0]?.headers['x-orca-hook-decision']).toBeUndefined()
})
it('keeps print-then-post for CLIs reusing Claude’s script, such as OpenClaude', async () => {
const { port, seen } = await hookServer(() => DENY)
expect(await runHook(PRE, { ORCA_AGENT_HOOK_PORT: String(port) }, false)).toBe('{}\n')
@@ -26,7 +26,8 @@ export function buildPosixClaudeDecisionModeLines(): string[] {
'case "$payload" in',
` *'"hook_event_name":"PreToolUse"'*|*'"hook_event_name": "PreToolUse"'*) orca_hook_decides=${CLAUDE_PRE_TOOL_USE_DECISION}; max_time=8 ;;`,
// Why 126 s: Orca answers within its 122 s hold; the managed entry's 130 s timeout outlasts both.
` *'"hook_event_name":"PermissionRequest"'*|*'"hook_event_name": "PermissionRequest"'*) orca_hook_decides=${CLAUDE_PERMISSION_REQUEST_DECISION}; max_time=126 ;;`,
// An async entry's output is ignored, so it answers `{}` first like any other event.
` *'"hook_event_name":"PermissionRequest"'*|*'"hook_event_name": "PermissionRequest"'*) if [ -n "\${ORCA_HOOK_ASYNC:-}" ]; then printf '{}\\n'; orca_hook_printed=1; else orca_hook_decides=${CLAUDE_PERMISSION_REQUEST_DECISION}; max_time=126; fi ;;`,
" *) printf '{}\\n'; orca_hook_printed=1 ;;",
'esac'
]
+32
View File
@@ -216,6 +216,38 @@ describe('ClaudeHookService.install', () => {
}
})
it.skipIf(process.platform === 'win32')(
'keeps a user-chosen async PermissionRequest async, without a decision wait',
() => {
const tmpHome = mkdtempSync(join(tmpdir(), 'orca-claude-async-'))
vi.stubEnv('HOME', tmpHome)
try {
const service = new ClaudeHookService()
service.install(CURRENT_CLAUDE)
const settingsPath = join(tmpHome, '.claude', 'settings.json')
type Hook = TestHook & { async?: boolean; timeout?: number }
const read = (): { hooks: Record<string, { hooks: Hook[] }[]> } =>
JSON.parse(readFileSync(settingsPath, 'utf-8'))
const settings = read()
const managed = settings.hooks.PermissionRequest[0].hooks[0]
settings.hooks.PermissionRequest[0].hooks[0] = { ...managed, async: true }
writeFileSync(settingsPath, JSON.stringify(settings), 'utf-8')
expect(service.getStatus(CURRENT_CLAUDE).state).toBe('installed')
expect(service.install(CURRENT_CLAUDE).state).toBe('installed')
expect(read().hooks.PermissionRequest[0].hooks[0]).toMatchObject({
async: true,
command: `export ORCA_HOOK_ASYNC=1; ${managed.command}`,
timeout: 10
})
expect(service.getStatus(CURRENT_CLAUDE).state).toBe('installed')
} finally {
vi.unstubAllEnvs()
rmSync(tmpHome, { recursive: true, force: true })
}
}
)
it('writes only the events an old resolved Claude knows and reports that as installed', () => {
const tmpHome = mkdtempSync(join(tmpdir(), 'orca-claude-old-version-'))
vi.stubEnv('HOME', tmpHome)
+4 -2
View File
@@ -209,7 +209,8 @@ export class ClaudeHookService {
(eventName) =>
getManagedEventHook(eventName, scriptPath, this.options.settings, exePath, { execForm }),
getManagedScriptFileName(this.options.settings),
plan
plan,
process.platform !== 'win32'
)
const payload = this.managedScript()
if (this.usesWindowsEntry) {
@@ -254,7 +255,8 @@ export class ClaudeHookService {
(eventName) =>
buildManagedCommandHook(getRemoteManagedEventCommand(eventName, remoteScriptPath)),
remoteScriptFileName,
this.managedHookPlan(options)
this.managedHookPlan(options),
true
)
// Publish scripts before settings can reference them.
+12 -3
View File
@@ -23,6 +23,10 @@ import {
} from '../agent-hooks/installation/commands/runtime-home-hook-command'
import { wrapWindowsDirectCmdHookCommand } from '../agent-hooks/installation/commands/windows-direct-cmd-hook-command'
import type { ClaudeManagedHookPlan } from './claude-managed-hook-events'
import {
claudeManagedHookForms,
withClaudeAsyncPermissionRequest
} from './claude-async-permission-request'
export type ClaudeCompatibleHookSettings = {
configDirName: '.claude' | '.openclaude' | '.qoder' | '.qoder-cn' | '.qwen' | '.codebuddy'
@@ -201,7 +205,7 @@ export function findManagedEventHookForms(
const hooks = Array.isArray(definitions)
? definitions.flatMap((definition) => definition.hooks ?? [])
: []
const form = formsFor(eventName).findIndex((expected) =>
const form = claudeManagedHookForms(eventName, formsFor(eventName)).findIndex((expected) =>
hooks.some((hook) => hasSameManagedHookInvocation(hook, expected))
)
if (form === -1) {
@@ -221,7 +225,8 @@ export function applyManagedHooks(
config: HooksConfig,
hookForEvent: (eventName: string) => HookCommandConfig,
scriptFileName: string,
plan: ClaudeManagedHookPlan
plan: ClaudeManagedHookPlan,
posixCommands: boolean
): HooksConfig {
const nextHooks = { ...config.hooks }
const isManagedCommand = createManagedCommandMatcher(scriptFileName)
@@ -229,7 +234,11 @@ export function applyManagedHooks(
for (const event of plan.install) {
const current = nextHooks[event.eventName]
const previous = Array.isArray(current) ? current : []
const hook = withPreviousManagedAsync(hookForEvent(event.eventName), previous, isManagedCommand)
const hook = withClaudeAsyncPermissionRequest(
event.eventName,
withPreviousManagedAsync(hookForEvent(event.eventName), previous, isManagedCommand),
posixCommands
)
const cleaned = removeManagedCommands(previous, isManagedCommand)
nextHooks[event.eventName] = [...cleaned, { ...event.definition, hooks: [hook] }]
}
@@ -16,7 +16,6 @@ import {
TerminalWorkerTurnStops
} from '../orchestration/workers/turn-stops/terminal-worker-turn-stops'
import { TerminalWorkerApprovalHolds } from '../orchestration/workers/approvals/terminal-worker-approval-holds'
import { showsClaudeDialog } from '../terminal/wait/claude-open-dialog-hold'
import type { WorkerTerminalResourceRow } from '../orchestration/terminal-authority/release/worker-terminal-ownership'
import { resolveStructuredWorkerIdentity } from '../orchestration/terminal-authority/structured-sessions/structured-worker-authority'
import {
@@ -83,9 +82,10 @@ export abstract class OrcaRuntimeWithAgentTransitions extends OrcaRuntimeWithWin
// Windows hooks print `{}` before they post; WSL and SSH relays answer for Claude.
return process.platform !== 'win32' && pty !== null && pty.connectionId === null && !pty.isWsl
},
showsDialog: (paneKey) => {
const lines = this.readLiveTerminalScreenLines(this.getPtyRecordForPaneKey(paneKey)?.ptyId)
return lines ? showsClaudeDialog(lines) : null
processIncarnation: (handle) => this.getTerminalProcessIncarnation(handle),
readScreen: (paneKey) => {
const ptyId = this.getPtyRecordForPaneKey(paneKey)?.ptyId
return ptyId ? (this.readCaughtUpRuledScreen(ptyId)?.lines ?? null) : null
},
setTimer: unrefTimer
})
@@ -16,6 +16,23 @@ import { TerminalWorkerApprovalHolds } from './terminal-worker-approval-holds'
const PANE = makePaneKey('tab-worker', '11111111-1111-4111-8111-111111111111')
const HANDLE = 'term_worker'
// Screens as Claude 2.1.322 leaves them (probe captures in design.md F2–F5).
const DIALOG = [
' Bash command',
' │ rm -rf build',
' Do you want to proceed?',
' ❯ 1. Yes',
' 2. No',
' Esc to cancel · Tab to amend'
]
const HOOK_DENIED = ['● Bash(rm -rf build)', ' ⎿ Denied by PermissionRequest hook']
const USER_NO = ['● Bash(rm -rf build)', ' ⎿ Interrupted · What should Claude do instead?']
const AUTO_BLOCKED = [
'● Bash(rm -rf build)',
' ⎿ Permission for this command was denied by a built-in Claude Code safety check'
]
const RAN = ['● Bash(rm -rf build)', ' ⎿ (No output)']
function setup(options: { canAnswer?: boolean } = {}) {
const db = new OrchestrationDb(':memory:')
const run = db.createRun({
@@ -25,13 +42,17 @@ function setup(options: { canAnswer?: boolean } = {}) {
})
const task = db.createTask({ spec: 'do the work', runId: run.id })
const dispatch = createRootDispatch(db, task.id, HANDLE, PANE)
const screen: { dialog: boolean | null } = { dialog: true }
const screen: { lines: readonly string[] | null; incarnation: string } = {
lines: DIALOG,
incarnation: 'run-1'
}
const timers: { run: () => void; cancelled: boolean }[] = []
const holds = new TerminalWorkerApprovalHolds({
notify: vi.fn(),
resolveWorker: () => ({ db, handle: HANDLE, dispatch }),
canAnswerPane: () => options.canAnswer ?? true,
showsDialog: () => screen.dialog,
processIncarnation: () => screen.incarnation,
readScreen: () => screen.lines,
setTimer: (run) => {
const timer = { run, cancelled: false }
timers.push(timer)
@@ -39,23 +60,28 @@ function setup(options: { canAnswer?: boolean } = {}) {
}
})
/** Runs every timer due now, then lets awaited replies settle. */
const tick = async (): Promise<void> => {
for (const timer of timers.splice(0)) {
if (!timer.cancelled) {
timer.run()
const tick = async (rounds = 1): Promise<void> => {
for (let i = 0; i < rounds; i++) {
for (const timer of timers.splice(0)) {
if (!timer.cancelled) {
timer.run()
}
}
await new Promise((resolve) => setImmediate(resolve))
}
await new Promise((resolve) => setImmediate(resolve))
}
const closing = () =>
db
.getUnreadRunMailbox(run.id, 100)
.filter((message) => message.type === 'status')
.map((message) => message.body)
return { db, dispatch, screen, holds, tick, closing }
return { dispatch, screen, holds, tick, closing }
}
function hook(toolUseId: string | undefined, promptId = 'prompt-1') {
function hook(
toolUseId: string | undefined,
onWrite?: (verdict: ClaudePermissionVerdict | null) => void
) {
const replies: (ClaudePermissionVerdict | null)[] = []
const ends: ((why: ClaudePermissionHoldEnd) => void)[] = []
const event: AgentHookEventPayload = {
@@ -63,23 +89,18 @@ function hook(toolUseId: string | undefined, promptId = 'prompt-1') {
connectionId: null,
hookEventName: 'PermissionRequest',
...(toolUseId ? { toolUseId } : {}),
payload: {
state: 'blocked',
prompt: '',
agentType: 'claude',
toolName: 'Bash',
toolInput: 'rm -rf build'
}
payload: { state: 'blocked', prompt: '', agentType: 'claude', toolName: 'Bash' }
}
return {
replies,
end: (why: ClaudePermissionHoldEnd) => ends.forEach((listener) => listener(why)),
request: {
event,
promptId,
promptId: 'prompt-1',
openChannel: () => ({
answer: async (verdict: ClaudePermissionVerdict | null) => {
replies.push(verdict)
onWrite?.(verdict)
return true
},
onEnd: (listener: (why: ClaudePermissionHoldEnd) => void) => {
@@ -100,89 +121,104 @@ function postToolUse(toolUseId: string): AgentHookEventPayload {
}
}
async function opened(ctx: ReturnType<typeof setup>, asked: ReturnType<typeof hook>) {
ctx.holds.admit(asked.request)
await ctx.tick()
return ctx.holds.takeOpenApproval(PANE, ctx.dispatch.id)!.approvalId
}
const deny = (ctx: ReturnType<typeof setup>, approvalId: string) =>
ctx.holds.answer({
dispatchId: ctx.dispatch.id,
approvalId,
decision: 'deny',
message: 'use a script file'
})
describe('terminal worker approval holds', () => {
it('passes requests it cannot name, or whose pane it cannot answer', () => {
expect(setup().holds.admit(hook(undefined).request)).toBe(false)
expect(setup({ canAnswer: false }).holds.admit(hook('tool-1').request)).toBe(false)
})
it('answers a deny once, with its message, and only when Claude takes it', async () => {
const { holds, screen, tick, dispatch } = setup()
const asked = hook('tool-1')
expect(holds.admit(asked.request)).toBe(true)
const approval = holds.takeOpenApproval(PANE, dispatch.id)
expect(approval).toMatchObject({ state: 'open', allowedActions: ['allow', 'deny'] })
it('claims a deny once Claude shows the hook denied it, and only once', async () => {
const ctx = setup()
const asked = hook('tool-1', () => (ctx.screen.lines = HOOK_DENIED))
const approvalId = await opened(ctx, asked)
const answering = holds.answer({
dispatchId: dispatch.id,
approvalId: approval!.approvalId,
decision: 'deny',
message: 'use a script file'
})
await tick()
screen.dialog = false
await tick()
expect(await answering).toMatchObject({ ok: true })
expect(await deny(ctx, approvalId)).toMatchObject({ ok: true })
expect(asked.replies).toEqual([{ behavior: 'deny', message: 'use a script file' }])
expect(
await holds.answer({
dispatchId: dispatch.id,
approvalId: approval!.approvalId,
decision: 'deny',
message: 'again'
})
).toMatchObject({ ok: false, code: 'approval_not_open' })
expect(await deny(ctx, approvalId)).toMatchObject({ ok: false, code: 'approval_not_open' })
})
it('says the answer was not taken when the dialog stays', async () => {
const { holds, tick, dispatch } = setup()
holds.admit(hook('tool-1').request)
const { approvalId } = holds.takeOpenApproval(PANE, dispatch.id)!
const answering = holds.answer({
dispatchId: dispatch.id,
approvalId,
decision: 'deny',
message: 'no'
})
for (let i = 0; i < 20; i++) {
await tick()
}
expect(await answering).toMatchObject({ ok: false, code: 'approval_refused' })
it('does not claim a deny that lost to a Yes in the terminal; the result names the Yes', async () => {
const ctx = setup()
const asked = hook('tool-1', () => (ctx.screen.lines = RAN))
const approvalId = await opened(ctx, asked)
expect(await deny(ctx, approvalId)).toMatchObject({ ok: false, code: 'approval_not_open' })
ctx.holds.observe(postToolUse('tool-1'))
expect(ctx.closing()).toEqual([expect.stringContaining("Allowed in the worker's terminal")])
})
it("does not claim a deny that lost to Claude's 2:00 auto-block", async () => {
const ctx = setup()
const asked = hook('tool-1', () => (ctx.screen.lines = AUTO_BLOCKED))
const approvalId = await opened(ctx, asked)
expect(await deny(ctx, approvalId)).toMatchObject({ ok: false, code: 'approval_not_open' })
expect(ctx.closing()).toEqual([expect.stringContaining('on its own (its 2:00 timeout)')])
})
it('writes nothing to a dialog the caught-up screen no longer shows', async () => {
const ctx = setup()
const asked = hook('tool-1')
const approvalId = await opened(ctx, asked)
ctx.screen.lines = USER_NO
expect(await deny(ctx, approvalId)).toMatchObject({ ok: false, code: 'approval_not_open' })
expect(asked.replies.filter(Boolean)).toEqual([])
})
it('refuses an answer once the agent in the pane was restarted', async () => {
const ctx = setup()
const asked = hook('tool-1')
const approvalId = await opened(ctx, asked)
ctx.screen.incarnation = 'run-2'
expect(await deny(ctx, approvalId)).toMatchObject({ ok: false, code: 'approval_not_open' })
expect(asked.replies).toEqual([])
})
it('releases both prompts when a second opens in the same pane', () => {
const { holds, dispatch } = setup()
const ctx = setup()
const first = hook('tool-1')
holds.admit(first.request)
expect(holds.admit(hook('tool-2').request)).toBe(false)
ctx.holds.admit(first.request)
expect(ctx.holds.admit(hook('tool-2').request)).toBe(false)
expect(first.replies).toEqual([null])
expect(holds.takeOpenApproval(PANE, dispatch.id)).toBeNull()
expect(ctx.holds.takeOpenApproval(PANE, ctx.dispatch.id)).toBeNull()
})
it('closes once the dialog leaves, and names an allow in the terminal from the tool result', async () => {
const { holds, screen, tick, dispatch, closing } = setup()
it('names a No in the terminal from the screen once the dialog leaves', async () => {
const ctx = setup()
const asked = hook('tool-1')
holds.admit(asked.request)
const { approvalId } = holds.takeOpenApproval(PANE, dispatch.id)!
await tick()
screen.dialog = false
await tick()
await opened(ctx, asked)
ctx.screen.lines = USER_NO
await ctx.tick()
expect(asked.replies).toEqual([null])
expect(
await holds.answer({ dispatchId: dispatch.id, approvalId, decision: 'deny', message: 'no' })
).toMatchObject({ ok: false, code: 'approval_not_open' })
holds.observe(postToolUse('tool-1'))
expect(closing()).toEqual([expect.stringContaining("Allowed in the worker's terminal")])
expect(ctx.closing()).toEqual([expect.stringContaining("Denied in the worker's terminal")])
})
it("names a deny in the terminal when Claude ends the waiting hook (the person's No)", () => {
const { holds, dispatch, closing } = setup()
it('treats a killed hook with the dialog still up as answerable only in the terminal', async () => {
const ctx = setup()
const asked = hook('tool-1')
holds.admit(asked.request)
holds.takeOpenApproval(PANE, dispatch.id)
await opened(ctx, asked)
asked.end('hook-gone')
expect(closing()).toEqual([expect.stringContaining("Denied in the worker's terminal")])
await ctx.tick(40)
expect(ctx.closing()).toEqual([
expect.stringContaining("a person must answer it in the worker's terminal")
])
})
})
@@ -1,5 +1,6 @@
/** Claude terminal workers' permission prompts, one record per waiting PermissionRequest hook. The
* record is answerable only while its hook waits and Claude's dialog is on the worker's screen. */
* record is answerable only while its hook waits and Claude's dialog is on the worker's screen, and
* how it closed is named only from what Claude leaves on that screen. */
import { createHash } from 'node:crypto'
import type {
ClaudePermissionHold,
@@ -8,6 +9,11 @@ import type {
ClaudePermissionHolds
} from '../../../../agent-hooks/server/claude-permission-hook-hold'
import type { AgentHookEventPayload } from '../../../../../shared/agent-hook-listener/listener-event'
import {
claudePermissionCloseEvidence,
claudeShowsHookAnswer,
showsClaudeDialog
} from '../../../terminal/wait/claude-open-dialog-hold'
import type { OrchestrationDb } from '../../db/orchestration-db'
import type { DispatchContextRow } from '../../db/orchestration-records'
import {
@@ -23,7 +29,8 @@ import type {
// Why 500 ms: Esc posts no hook, so only the screen says the dialog left; a click is refused within it.
const DIALOG_POLL_MS = 500
// Why 3 s: Claude closes its dialog at once on a hook's answer (probe F2); longer means it was not taken.
const ANSWER_TAKEN_WAIT_MS = 3_000
const SCREEN_WAIT_MS = 3_000
const SCREEN_RETRY_MS = 100
// A closed prompt waits this long for its tool's result before its closing line says no more than "closed".
const CLOSE_EVIDENCE_MS = 10 * 60_000
@@ -34,36 +41,36 @@ export type TerminalWorkerApprovalHoldsDeps = Pick<WorkerTurnStopReportDeps, 'no
) => { db: OrchestrationDb; handle: string; dispatch: DispatchContextRow } | null
/** False where a hook's answer cannot reach Claude: Windows, WSL and SSH panes. */
canAnswerPane: (paneKey: string) => boolean
/** Whether Claude's permission dialog is on the pane's screen now; null when unreadable. */
showsDialog: (paneKey: string) => boolean | null
/** The pane's process run; a restarted agent is a different prompt. */
processIncarnation: (handle: string) => string | null
/** The pane's screen once it has applied every PTY chunk; null while it lags or is unreadable. */
readScreen: (paneKey: string) => readonly string[] | null
setTimer: (run: () => void, delayMs: number) => { cancel: () => void }
}
type Hold = {
approvalId: string
key: string
paneKey: string
toolUseId: string
handle: string
incarnation: string | null
db: OrchestrationDb
dispatch: DispatchContextRow
summary: WorkerApprovalPayload['summary']
channel: ClaudePermissionHookChannel
/** Compare-and-set: only the step out of `open` may write a decision to the hook. */
state: 'open' | 'answered' | 'closed'
state: 'open' | 'answering' | 'answered' | 'closed'
dialogSeen: boolean
/** The coordinator was told about it, so it is owed one closing line. */
reported: boolean
timer: { cancel: () => void } | null
}
type CloseHow = Pick<WorkerApprovalOutcome, 'by' | 'decision'>
export type TerminalWorkerApprovalAnswer =
| { ok: true; approval: WorkerApprovalPayload }
| {
ok: false
code: 'approval_not_open' | 'approval_refused'
message: string
}
| { ok: false; code: 'approval_not_open'; message: string }
export class TerminalWorkerApprovalHolds implements ClaudePermissionHolds {
private readonly byApprovalId = new Map<string, Hold>()
@@ -87,16 +94,18 @@ export class TerminalWorkerApprovalHolds implements ClaudePermissionHolds {
const other = this.openByPane.get(paneKey)
if (other) {
// Two prompts in one pane: the screen cannot say which one it shows, so neither is answerable.
this.close(other, null)
this.close(other, { by: 'terminal-only', decision: null })
return false
}
const key = JSON.stringify([promptId, toolUseId])
const hold: Hold = {
approvalId: `apr_${createHash('sha256').update(key).digest('hex').slice(0, 16)}`,
key,
approvalId: `apr_${createHash('sha256')
.update(JSON.stringify([promptId, toolUseId]))
.digest('hex')
.slice(0, 16)}`,
paneKey,
toolUseId,
handle: worker.handle,
incarnation: this.deps.processIncarnation(worker.handle),
db: worker.db,
dispatch: worker.dispatch,
summary: {
@@ -112,7 +121,7 @@ export class TerminalWorkerApprovalHolds implements ClaudePermissionHolds {
}
this.byApprovalId.set(hold.approvalId, hold)
this.openByPane.set(paneKey, hold)
hold.channel.onEnd((why) => this.ended(hold, why))
hold.channel.onEnd((why) => void this.ended(hold, why))
this.watchDialog(hold)
return true
}
@@ -123,7 +132,7 @@ export class TerminalWorkerApprovalHolds implements ClaudePermissionHolds {
const open = this.openByPane.get(event.paneKey)
const hold =
open?.toolUseId === event.toolUseId ? open : this.closingByToolUseId.get(event.toolUseId)
if (hold?.paneKey === event.paneKey) {
if (hold?.paneKey === event.paneKey && hold.state !== 'answering') {
this.close(hold, { by: 'worker-terminal', decision: 'allow' })
}
return
@@ -151,42 +160,44 @@ export class TerminalWorkerApprovalHolds implements ClaudePermissionHolds {
return this.payload(hold)
}
/** Writes a decision only to a dialog still on a caught-up screen, and claims it only once Claude
* shows it applied: a Yes, a No or the 2:00 auto-block that won the race names its own close. */
async answer(input: {
dispatchId: string
approvalId: string
decision: WorkerApprovalDecision
message: string
}): Promise<TerminalWorkerApprovalAnswer> {
const hold = this.byApprovalId.get(input.approvalId)
const worker = hold ? this.deps.resolveWorker(hold.paneKey) : null
if (
!hold ||
hold.dispatch.id !== input.dispatchId ||
hold.state !== 'open' ||
worker?.dispatch.id !== hold.dispatch.id ||
worker.handle !== hold.handle ||
this.deps.showsDialog(hold.paneKey) === false
) {
return {
ok: false,
code: 'approval_not_open',
message: `This prompt is no longer open: ${input.approvalId} was answered, or left the worker's screen.`
}
const notOpen: TerminalWorkerApprovalAnswer = {
ok: false,
code: 'approval_not_open',
message: `This prompt is no longer open: ${input.approvalId} was answered, or left the worker's screen.`
}
hold.state = 'answered'
this.release(hold)
const hold = this.byApprovalId.get(input.approvalId)
if (!hold || hold.dispatch.id !== input.dispatchId || !this.stillBound(hold)) {
return notOpen
}
const before = await this.screenWhere(hold.paneKey, () => true)
if (hold.state !== 'open' || !before || !showsClaudeDialog(before)) {
return notOpen
}
hold.state = 'answering'
hold.timer?.cancel()
const written = await hold.channel.answer(
input.decision === 'allow'
? { behavior: 'allow' }
: { behavior: 'deny', message: input.message }
)
if (!written || !(await this.dialogLeaves(hold.paneKey))) {
return {
ok: false,
code: 'approval_refused',
message: `The worker did not take the answer to ${input.approvalId}; a person must answer it in the worker's terminal.`
}
const after = written
? await this.screenWhere(hold.paneKey, (lines) => !showsClaudeDialog(lines))
: null
if (!after || !claudeShowsHookAnswer(after, input.decision)) {
hold.state = 'open'
this.settleFromScreen(hold, after)
return notOpen
}
hold.state = 'answered'
this.release(hold)
return { ok: true, approval: this.payload(hold) }
}
@@ -195,10 +206,10 @@ export class TerminalWorkerApprovalHolds implements ClaudePermissionHolds {
if (hold.state !== 'open') {
return
}
const shown = this.deps.showsDialog(hold.paneKey)
const lines = this.deps.readScreen(hold.paneKey)
const shown = lines ? showsClaudeDialog(lines) : null
if (shown === false && hold.dialogSeen) {
// The person answered, Esc dismissed it, or Claude's 2:00 auto-block fired; the result says which.
this.closeAwaitingEvidence(hold)
this.settleFromScreen(hold, lines)
return
}
hold.dialogSeen ||= shown === true
@@ -206,9 +217,37 @@ export class TerminalWorkerApprovalHolds implements ClaudePermissionHolds {
}, DIALOG_POLL_MS)
}
private ended(hold: Hold, why: ClaudePermissionHoldEnd): void {
// Claude ends a waiting hook only when the person presses No (probe F3).
this.close(hold, why === 'hook-gone' ? { by: 'worker-terminal', decision: 'deny' } : null)
/** A hang-up is not an answer: a killed or crashed hook leaves the dialog up (probes F6, F11). */
private async ended(hold: Hold, why: ClaudePermissionHoldEnd): Promise<void> {
if (why !== 'hook-gone' || hold.state !== 'open') {
this.close(hold, null)
return
}
const lines = await this.screenWhere(hold.paneKey, (screen) => !showsClaudeDialog(screen))
this.settleFromScreen(hold, lines)
}
/** Names a close from the screen Claude left: No, the auto-block, or nothing yet (wait for a result). */
private settleFromScreen(hold: Hold, lines: readonly string[] | null): void {
if (hold.state !== 'open') {
return
}
if (!lines || showsClaudeDialog(lines)) {
// The dialog is up but Orca can no longer answer it: a person must, in the terminal.
this.close(hold, { by: 'terminal-only', decision: null })
return
}
switch (claudePermissionCloseEvidence(lines)) {
case 'user-interrupted':
this.close(hold, { by: 'worker-terminal', decision: 'deny' })
return
case 'auto-denied':
this.close(hold, { by: 'auto', decision: 'deny' })
return
case 'hook-denied':
case null:
this.closeAwaitingEvidence(hold)
}
}
private closeAwaitingEvidence(hold: Hold): void {
@@ -223,7 +262,7 @@ export class TerminalWorkerApprovalHolds implements ClaudePermissionHolds {
}
/** Ends a record not answered through Orca; a reported one gets its one closing line. */
private close(hold: Hold, how: Pick<WorkerApprovalOutcome, 'by' | 'decision'> | null): void {
private close(hold: Hold, how: CloseHow | null): void {
if (hold.state === 'answered') {
return
}
@@ -260,22 +299,34 @@ export class TerminalWorkerApprovalHolds implements ClaudePermissionHolds {
this.byApprovalId.delete(hold.approvalId)
}
private dialogLeaves(paneKey: string): Promise<boolean> {
/** Still the worker, Dispatch and process run the prompt was raised in. */
private stillBound(hold: Hold): boolean {
const worker = this.deps.resolveWorker(hold.paneKey)
return (
worker?.dispatch.id === hold.dispatch.id &&
worker.handle === hold.handle &&
this.deps.processIncarnation(hold.handle) === hold.incarnation
)
}
/** The first caught-up screen that passes `until`, or the last caught-up one within the wait. */
private screenWhere(
paneKey: string,
until: (lines: readonly string[]) => boolean
): Promise<readonly string[] | null> {
return new Promise((resolve) => {
let waited = 0
let last: readonly string[] | null = null
const check = (): void => {
if (this.deps.showsDialog(paneKey) === false) {
resolve(true)
last = this.deps.readScreen(paneKey) ?? last
if ((last && until(last)) || waited >= SCREEN_WAIT_MS) {
resolve(last)
return
}
waited += DIALOG_POLL_MS / 2
if (waited > ANSWER_TAKEN_WAIT_MS) {
resolve(false)
return
}
this.deps.setTimer(check, DIALOG_POLL_MS / 2)
waited += SCREEN_RETRY_MS
this.deps.setTimer(check, SCREEN_RETRY_MS)
}
this.deps.setTimer(check, DIALOG_POLL_MS / 2)
check()
})
}
@@ -7,12 +7,16 @@ import type {
export type WorkerApprovalDecision = 'allow' | 'deny'
export type WorkerApprovalState = 'open' | 'answered' | 'expired'
/** Who settled it: a person (in Orca), the coordinator agent, someone in the worker's own chat or terminal, or no one Orca can name. */
/** Who settled it: a person (in Orca), the coordinator agent, someone in the worker's own chat or
* terminal, the agent's own timeout, or no one Orca can name. `terminal-only`: still open, but only
* a person at the worker's terminal can answer it now. */
export type WorkerApprovalAnswerer =
| 'person'
| 'coordinator'
| 'worker-chat'
| 'worker-terminal'
| 'auto'
| 'terminal-only'
| 'unknown'
export type WorkerApprovalOutcome = {
@@ -221,6 +221,8 @@ const CLOSED_BY: Record<NonNullable<WorkerApprovalPayload['outcome']>['by'], str
coordinator: 'by the coordinator',
'worker-chat': "in the worker's own chat",
'worker-terminal': "in the worker's terminal",
auto: "by the worker's agent on its own (its 2:00 timeout)",
'terminal-only': "for Orca; a person must answer it in the worker's terminal",
unknown: 'without an answer Orca can name'
}
@@ -240,7 +242,7 @@ function describeApprovalClosed(approval: WorkerApprovalPayload): string {
])
]
: []),
'Nothing to do unless the worker stays stuck.'
...(outcome?.by === 'terminal-only' ? [] : ['Nothing to do unless the worker stays stuck.'])
].join('\n')
}
@@ -63,9 +63,7 @@ export const ORCHESTRATION_WORKER_APPROVAL_METHODS = [
message: access.reason ?? 'Denied by the owner.'
})
if (!answered.ok) {
throw new OrchestrationError(answered.code, answered.message, {
effectsApplied: answered.code === 'approval_refused'
})
throw new OrchestrationError(answered.code, answered.message, { effectsApplied: false })
}
reportWorkerApprovalClosed(
db,
@@ -43,3 +43,40 @@ export function showsClaudeDialog(lines: readonly string[]): boolean {
const region = lines.filter((line) => line.trim() !== '').slice(-DIALOG_REGION_LINES)
return region.some((line) => DIALOG_FOOTER_RE.test(line)) || hasCursoredOptionList(region)
}
/** How Claude's permission dialog closed, from the lines it leaves at the bottom of the screen. */
export type ClaudePermissionCloseEvidence = 'hook-denied' | 'user-interrupted' | 'auto-denied'
// Why the bottom lines only: an older prompt's close stays in scrollback above the newest one.
const CLOSE_EVIDENCE_LINES = 10
const CLOSE_EVIDENCE: readonly [RegExp, ClaudePermissionCloseEvidence][] = [
[/Denied by PermissionRequest hook/, 'hook-denied'],
// Why String.raw: the orcad bundle must stay ASCII (see CURSORED_OPTION_RE).
[new RegExp(String.raw`Interrupted \u00B7 What should Claude do instead\?`), 'user-interrupted'],
[/denied by a built-in Claude Code safety check/, 'auto-denied']
]
export function claudePermissionCloseEvidence(
lines: readonly string[]
): ClaudePermissionCloseEvidence | null {
const bottom = lines.filter((line) => line.trim() !== '').slice(-CLOSE_EVIDENCE_LINES)
for (const [pattern, evidence] of CLOSE_EVIDENCE) {
if (bottom.some((line) => pattern.test(line))) {
return evidence
}
}
return null
}
/** Claude's dialog left with the hook's answer applied: a deny shows the hook's line, and an allow
* shows no other close. A person's Yes looks the same as the hook's allow. */
export function claudeShowsHookAnswer(
lines: readonly string[],
decision: 'allow' | 'deny'
): boolean {
if (showsClaudeDialog(lines)) {
return false
}
const evidence = claudePermissionCloseEvidence(lines)
return evidence === 'hook-denied' || (decision === 'allow' && evidence === null)
}