@cogitator-ai/bridge 0.5.0 → 0.6.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (70) hide show
  1. package/README.md +19 -16
  2. package/dist/adapter.d.ts +33 -2
  3. package/dist/adapter.d.ts.map +1 -1
  4. package/dist/adapters/claude.d.ts +95 -2
  5. package/dist/adapters/claude.d.ts.map +1 -1
  6. package/dist/adapters/claude.js +207 -3
  7. package/dist/adapters/claude.js.map +1 -1
  8. package/dist/adapters/hosted.d.ts +3 -2
  9. package/dist/adapters/hosted.d.ts.map +1 -1
  10. package/dist/adapters/hosted.js +2 -1
  11. package/dist/adapters/hosted.js.map +1 -1
  12. package/dist/client.d.ts +11 -1
  13. package/dist/client.d.ts.map +1 -1
  14. package/dist/client.js +14 -0
  15. package/dist/client.js.map +1 -1
  16. package/dist/dispatcher.d.ts +33 -1
  17. package/dist/dispatcher.d.ts.map +1 -1
  18. package/dist/dispatcher.js +112 -4
  19. package/dist/dispatcher.js.map +1 -1
  20. package/dist/index.d.ts +7 -5
  21. package/dist/index.d.ts.map +1 -1
  22. package/dist/index.js +2 -1
  23. package/dist/index.js.map +1 -1
  24. package/dist/inputs.d.ts +24 -0
  25. package/dist/inputs.d.ts.map +1 -1
  26. package/dist/inputs.js +4 -0
  27. package/dist/inputs.js.map +1 -1
  28. package/dist/permit.d.ts +43 -0
  29. package/dist/permit.d.ts.map +1 -0
  30. package/dist/permit.js +118 -0
  31. package/dist/permit.js.map +1 -0
  32. package/dist/person-channel.d.ts.map +1 -1
  33. package/dist/person-channel.js +6 -0
  34. package/dist/person-channel.js.map +1 -1
  35. package/dist/person-inbox.d.ts +2 -1
  36. package/dist/person-inbox.d.ts.map +1 -1
  37. package/dist/person-inbox.js +10 -1
  38. package/dist/person-inbox.js.map +1 -1
  39. package/dist/person.d.ts +13 -0
  40. package/dist/person.d.ts.map +1 -1
  41. package/dist/person.js +1 -0
  42. package/dist/person.js.map +1 -1
  43. package/dist/protocol.d.ts +2 -0
  44. package/dist/protocol.d.ts.map +1 -1
  45. package/dist/protocol.js +2 -0
  46. package/dist/protocol.js.map +1 -1
  47. package/dist/server.d.ts.map +1 -1
  48. package/dist/server.js +2 -0
  49. package/dist/server.js.map +1 -1
  50. package/dist/setup/claude.d.ts +4 -2
  51. package/dist/setup/claude.d.ts.map +1 -1
  52. package/dist/setup/claude.js +9 -3
  53. package/dist/setup/claude.js.map +1 -1
  54. package/dist/testing/fake-harnesses.d.ts +15 -2
  55. package/dist/testing/fake-harnesses.d.ts.map +1 -1
  56. package/dist/testing/fake-harnesses.js +17 -2
  57. package/dist/testing/fake-harnesses.js.map +1 -1
  58. package/dist/tools/index.d.ts +1 -1
  59. package/dist/tools/index.js +1 -1
  60. package/dist/tools/tools.d.ts +1 -1
  61. package/dist/tools/tools.js +2 -2
  62. package/dist/tools/tools.js.map +1 -1
  63. package/dist/types.d.ts +6 -0
  64. package/dist/types.d.ts.map +1 -1
  65. package/dist/types.js +2 -0
  66. package/dist/types.js.map +1 -1
  67. package/fakes/claude.mjs +175 -8
  68. package/fakes/lib.mjs +58 -7
  69. package/fakes/mcp.mjs +6 -1
  70. package/package.json +4 -4
package/README.md CHANGED
@@ -201,7 +201,9 @@ An agent that carries a job out sometimes needs leave for one call: to run a com
201
201
 
202
202
  So an agent never gets leave from another agent that the other one does not have itself. A job handed over from inside a job is bound by every agent up the chain. Without a rule the person is asked what a person at a session would be asked: a command, an address to fetch, a file outside the project. A change to the settings files themselves is always the person's to allow, whatever the rules and the mode say, and so is a command that names their folders: an agent does not write the rules it is judged by. For a command this reads the words of the command line and no more, as every rule on a command does.
203
203
 
204
- The one who asked does not get the answer as mail: it waits for it with `verdict({ letter })`, which answers the moment the request is decided. A request whose job ends first counts as refused. The same call may be asked for again once it was allowed, and is held back as a repeat once it was refused.
204
+ The one who asked does not get the answer as mail: it waits for it with `verdict({ letter })`, which answers the moment the request is decided. A request whose job ends first counts as refused. One that stops waiting takes its request back with `withdraw({ letter })`: nobody is asked to decide it any more, and an answer that comes late is refused instead of looking as if it let the call through. The same call may be asked for again once it was allowed, and is held back as a repeat once it was refused.
205
+
206
+ A Claude Code session the bridge starts asks the same way. It gets a `PermissionRequest` hook (`cogitator bridge permit`), so a call its mode and rules would show the permission dialog for becomes a request on its job, and the session goes on with the verdict. A session you opened keeps its dialog, which is yours to answer. When it opens one while it carries out a job, a `Notification` hook that `cogitator bridge install` adds (`cogitator bridge stuck`) tells the bridge: the agent that handed the job over gets a note that the job stands still, and you a notice in the inbox and the chat. A background session is noticed the same way in what `claude agents --json` lists. Codex gives no such signal yet, so a thread that waits at its own approval prompt is noticed by the reply timeout.
205
207
 
206
208
  An agent can also leave a letter to the person itself: `answer` with the decision `person` (`escalate` in code) passes a question or a request on, and the person's answer goes straight to the one who asked.
207
209
 
@@ -255,19 +257,20 @@ Folders are compared by their real path, so a project reached through a symlink
255
257
 
256
258
  Each number is a default that `hostBridge({ limits })` changes.
257
259
 
258
- | Limit | Default | What happens |
259
- | ----------------- | ---------- | ---------------------------------------------------------------------------------------------------- |
260
- | Depth | 3 | A job handed over from inside a job from inside a job is the deepest. One more is refused |
261
- | Letters per job | 60 | The job fails, both sides are told. The report that ends the job always goes through |
262
- | Time per job | 4 hours | The job fails, both sides are told |
263
- | Reply timeout | 30 minutes | The one who owes an answer, or did not pick a job up, is reminded. After as long again the job fails |
264
- | Jobs out | 20 | An agent with that many jobs still in progress cannot hand over another |
265
- | Jobs per hour | 60 | Handing over faster is refused as a loop |
266
- | Sessions starting | 2 | No more sessions are started at once |
267
- | Silence | 12 hours | A session with no job in progress is taken for gone, unless its harness lists it or its hook waits |
268
- | Session check | 1 minute | How often a harness that can list its sessions is asked which of them still run |
269
- | Person's answer | 4 hours | The person is reminded of a letter that waits for them. After as long again the job fails |
270
- | Delivery | 5 attempts | Retried with a growing wait, then left for the inbox |
260
+ | Limit | Default | What happens |
261
+ | ----------------- | ---------- | ------------------------------------------------------------------------------------------------------------------------ |
262
+ | Depth | 3 | A job handed over from inside a job from inside a job is the deepest. One more is refused |
263
+ | Letters per job | 60 | The job fails, both sides are told. The report that ends the job always goes through |
264
+ | Time per job | 4 hours | The job fails, both sides are told |
265
+ | Reply timeout | 30 minutes | The one who owes an answer, or did not pick a job up, is reminded. After as long again the job fails |
266
+ | Jobs out | 20 | An agent with that many jobs still in progress cannot hand over another |
267
+ | Jobs per hour | 60 | Handing over faster is refused as a loop |
268
+ | Sessions starting | 2 | No more sessions are started at once |
269
+ | Silence | 12 hours | A session with no job in progress is taken for gone, unless its harness lists it or its hook waits |
270
+ | Session check | 1 minute | How often a harness that can list its sessions is asked which of them still run |
271
+ | Window notice | 10 minutes | An agent that waits for a person at its own window is said so to whoever handed it a job, and not again within this time |
272
+ | Person's answer | 4 hours | The person is reminded of a letter that waits for them. After as long again the job fails |
273
+ | Delivery | 5 attempts | Retried with a growing wait, then left for the inbox |
271
274
 
272
275
  Two more rules have no number. A letter that says what the previous one in the same direction said is not delivered, and neither is a job the same agent already has from the caller and has not finished.
273
276
 
@@ -347,7 +350,7 @@ A session of a provider stays in the folder it was opened for: a later job for a
347
350
  `cogitator bridge mcp` is a few lines over `@cogitator-ai/bridge/tools`, which needs `@cogitator-ai/core`:
348
351
 
349
352
  ```typescript
350
- import { MCPServer } from '@cogitator-ai/mcp';
353
+ import { MCPServer } from '@cogitator-ai/mcp/server';
351
354
  import { bridgePaths } from '@cogitator-ai/bridge';
352
355
  import { BRIDGE_INSTRUCTIONS, bridgeTools } from '@cogitator-ai/bridge/tools';
353
356
 
@@ -447,7 +450,7 @@ for (const conformance of adapterConformanceCases(target)) {
447
450
 
448
451
  ## Trust
449
452
 
450
- The bridge is a tool of one person on one machine. The socket and the database are created for their owner only, a folder or a database that belongs to another user is refused, and every process of that user can connect: read any job and letter, and call as a session by naming its id. A job is done inside the project it is handed over in, or the worktree its caller works in. A session the bridge starts has the rights its harness gives it: a Claude Code session the permission mode you configure (`claudeCodeAdapter({ permissionMode })`), a Codex thread the `workspace-write` sandbox unless you choose another (`codexAdapter({ sandbox })`). A letter is text from another agent, never an order from you: every letter says so in its first line, and whether a session you opened takes a job without asking you is yours to say at `cogitator bridge install` (`--take-jobs`). A tool call names its session the way a connection to the socket does, and is believed the same way. Do not point `COGITATOR_BRIDGE_HOME` at a folder other users can write to. A permission request is judged by the settings files of the job's project as they are on disk when it is asked. An answer of the person comes over the socket from a connection that named no session: the command line refuses to answer for the person from inside a session of an agent, which keeps an agent from doing so by accident and does not stop a process that hides what it is. A Telegram chat is as private as the token of its bot. On Windows the dispatcher listens on a named pipe that other users of the same machine can reach, so run it only on a machine you do not share. The Claude Code and Codex adapters run on macOS and Linux.
453
+ The bridge is a tool of one person on one machine. The socket and the database are created for their owner only, a folder or a database that belongs to another user is refused, and every process of that user can connect: read any job and letter, and call as a session by naming its id. A job is done inside the project it is handed over in, or the worktree its caller works in. A session the bridge starts reads the whole project and changes files only in the folder of its job: a Claude Code session runs in `acceptEdits` mode unless you choose another (`claudeCodeAdapter({ permissionMode })`, `bridge serve --claude-mode`), a Codex thread in the `workspace-write` sandbox unless you choose another (`codexAdapter({ sandbox })`, `--codex-sandbox`), an agent behind a session provider in `acceptEdits`. Claude Code has a background session change the files of a git repository in a worktree of its own (`.claude/worktrees/<name>`, the branch `worktree-<name>`), so what such a session changed is there and not in your checkout, uncommitted unless it committed, and its report says where. What goes beyond that, a command, an address, a file elsewhere, is decided by the rules of the project and, where they are silent, asked through the bridge. An agent of the runtime has the permissions its own code gives it. A letter is text from another agent, never an order from you: every letter says so in its first line, and whether a session you opened takes a job without asking you is yours to say at `cogitator bridge install` (`--take-jobs`). A tool call names its session the way a connection to the socket does, and is believed the same way. Do not point `COGITATOR_BRIDGE_HOME` at a folder other users can write to. A permission request is judged by the settings files of the job's project as they are on disk when it is asked. An answer of the person comes over the socket from a connection that named no session: the command line refuses to answer for the person from inside a session of an agent, which keeps an agent from doing so by accident and does not stop a process that hides what it is. A Telegram chat is as private as the token of its bot. On Windows the dispatcher listens on a named pipe that other users of the same machine can reach, so run it only on a machine you do not share. The Claude Code and Codex adapters run on macOS and Linux.
451
454
 
452
455
  ## Errors
453
456
 
package/dist/adapter.d.ts CHANGED
@@ -1,6 +1,6 @@
1
- import type { CreateJobInput, CreateJobResult, InboxInput, SendLetterInput, SendLetterResult, VerdictInput, VerdictResult } from './inputs.js';
1
+ import type { CreateJobInput, CreateJobResult, InboxInput, SendLetterInput, SendLetterResult, VerdictInput, VerdictResult, WithdrawInput, WithdrawResult } from './inputs.js';
2
2
  import type { LetterFilter } from './store/store.js';
3
- import type { AdapterCapabilities, AgentRecord, BridgeJob, CallerIdentity, Letter, RenderedLetter } from './types.js';
3
+ import type { AdapterCapabilities, AgentRecord, BridgeJob, CallerIdentity, Letter, PermissionAsk, RenderedLetter, Verdict } from './types.js';
4
4
  /** A letter on its way to a session, as an adapter gets it. */
5
5
  export interface LetterDelivery {
6
6
  agent: AgentRecord;
@@ -30,6 +30,16 @@ export interface CreatedSession {
30
30
  /** Whether the session got `firstLetter` when it started, so the bridge does not deliver it again */
31
31
  deliveredFirstLetter?: boolean;
32
32
  }
33
+ /** A call a session needs leave for, as its harness told a hook. */
34
+ export interface PermissionHookCall {
35
+ /** The session that makes the call */
36
+ caller: CallerIdentity;
37
+ ask: PermissionAsk;
38
+ /** The words of the letter that asks leave */
39
+ body: string;
40
+ /** What the hook writes to tell the harness the decision */
41
+ answer(verdict: Verdict, reason: string): string;
42
+ }
33
43
  /** A session of a harness that runs on this machine right now, as the harness lists it. */
34
44
  export interface LiveSession {
35
45
  sessionId: string;
@@ -37,6 +47,11 @@ export interface LiveSession {
37
47
  name?: string;
38
48
  /** In the middle of a turn */
39
49
  busy?: boolean;
50
+ /**
51
+ * What the session waits for from a person at its window, in the words of its harness, such
52
+ * as `permission prompt`. Absent for a session that waits for nobody
53
+ */
54
+ waitingFor?: string;
40
55
  }
41
56
  /** What tells a process of a harness apart: its environment and, for a hook, what the harness wrote to it. */
42
57
  export interface IdentifyContext {
@@ -72,6 +87,7 @@ export interface BridgeCalls {
72
87
  createJob(caller: string, input: CreateJobInput): Promise<CreateJobResult>;
73
88
  send(caller: string, input: SendLetterInput): Promise<SendLetterResult>;
74
89
  verdict(caller: string, input: VerdictInput, signal?: AbortSignal): Promise<VerdictResult>;
90
+ withdraw(caller: string, input: WithdrawInput): Promise<WithdrawResult>;
75
91
  inbox(caller: string, input?: InboxInput): Promise<RenderedLetter[]>;
76
92
  acknowledge(caller: string, letterId: string): Promise<Letter>;
77
93
  cancel(caller: string, job: number, reason?: string): Promise<BridgeJob>;
@@ -115,6 +131,21 @@ export interface BridgeAdapter {
115
131
  * on as it was. For a harness whose server of tools outlives its sessions
116
132
  */
117
133
  toolCallHook?(context: IdentifyContext): string | undefined;
134
+ /**
135
+ * Reads what the harness wrote to a hook that runs when a session needs leave for a call: who
136
+ * asks, for what, and how to tell the harness the decision. Undefined when the input is not
137
+ * that of such a hook
138
+ */
139
+ permissionHook?(context: IdentifyContext): PermissionHookCall | undefined;
140
+ /**
141
+ * Reads what the harness wrote to a hook that runs when a session begins to wait for a person
142
+ * at its own window: who waits, and for what. Undefined when the input is not that of such a
143
+ * hook
144
+ */
145
+ stuckHook?(context: IdentifyContext): {
146
+ caller: CallerIdentity;
147
+ what: string;
148
+ } | undefined;
118
149
  /**
119
150
  * The sessions of the harness running on this machine, when the harness can list them. The
120
151
  * bridge keeps a listed session in its address book however long it is silent, and takes one
@@ -1 +1 @@
1
- {"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../src/adapter.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../src/adapter.ts"],"names":[],"mappings":"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"}
@@ -1,4 +1,5 @@
1
- import type { BridgeAdapter } from '../adapter.js';
1
+ import type { BridgeAdapter, PermissionHookCall } from '../adapter.js';
2
+ import { type CallerIdentity } from '../types.js';
2
3
  import { type ToolsServerCommand } from './tools-server.js';
3
4
  /** How letters reach a Claude Code session: a hook of the session waits for them. */
4
5
  export declare const CLAUDE_DELIVERY = "hook";
@@ -81,6 +82,94 @@ export declare function hasClaudeToolsHook(settings: unknown): boolean;
81
82
  * @param hookInput what Claude Code wrote to the hook's stdin
82
83
  */
83
84
  export declare function claudeToolCallHook(hookInput: string): string | undefined;
85
+ export interface ClaudePermitHookOptions {
86
+ /** How the bridge's command line is run, `cogitator bridge` by default */
87
+ bridgeCommand?: string;
88
+ /**
89
+ * The name the bridge gave the session it starts. With it a call the session asks leave for
90
+ * before the bridge has learned its id still belongs to the job it was started for
91
+ */
92
+ agentName?: string;
93
+ /** The folder of the bridge's files, when it is not the default one */
94
+ bridgeHome?: string;
95
+ /** Seconds the hook may wait for the decision before Claude Code ends it, 12 hours by default */
96
+ timeoutS?: number;
97
+ }
98
+ export interface ClaudePermitHookSettings {
99
+ hooks: {
100
+ PermissionRequest: {
101
+ hooks: {
102
+ type: 'command';
103
+ command: string;
104
+ timeout: number;
105
+ }[];
106
+ }[];
107
+ };
108
+ }
109
+ /** The command a hook of a Claude Code session runs to ask leave for a call through the bridge. */
110
+ export declare function claudePermitCommand(options?: ClaudePermitHookOptions): string;
111
+ /**
112
+ * The settings that make a Claude Code session ask leave through the bridge: a
113
+ * `PermissionRequest` hook, which Claude Code runs for every call its mode and rules would
114
+ * show the permission dialog for. The hook takes the call to the bridge and answers with the
115
+ * verdict. They are for a session the bridge starts, where nobody sits to answer the dialog: a
116
+ * session without them waits on its first dialog until its job fails. A session a person opened
117
+ * does not get them, the dialog there is the person's.
118
+ */
119
+ export declare function claudePermitHook(options?: ClaudePermitHookOptions): ClaudePermitHookSettings;
120
+ export interface ClaudeStuckHookOptions {
121
+ /** How the bridge's command line is run, `cogitator bridge` by default */
122
+ bridgeCommand?: string;
123
+ /** The folder of the bridge's files, when it is not the default one */
124
+ bridgeHome?: string;
125
+ }
126
+ export interface ClaudeStuckHookSettings {
127
+ hooks: {
128
+ Notification: {
129
+ matcher: string;
130
+ hooks: {
131
+ type: 'command';
132
+ command: string;
133
+ timeout: number;
134
+ async: true;
135
+ }[];
136
+ }[];
137
+ };
138
+ }
139
+ /**
140
+ * The permission mode of a Claude Code session the bridge starts, unless the adapter is told
141
+ * another: edits inside the folder of the job need no leave, everything else goes by the rules
142
+ * of the project and, where they are silent, through the bridge.
143
+ */
144
+ export declare const CLAUDE_SESSION_MODE = "acceptEdits";
145
+ /** The command a hook of a Claude Code session runs when the session waits for a person. */
146
+ export declare function claudeStuckCommand(options?: ClaudeStuckHookOptions): string;
147
+ /**
148
+ * The settings that tell the bridge a Claude Code session waits for a person at its window: a
149
+ * `Notification` hook for permission prompts, which Claude Code runs when it opens its
150
+ * permission dialog. The hook runs in the background and decides nothing: it only lets the
151
+ * agent that handed the session a job know that the job stands still until a person answers.
152
+ * For the sessions a person opens, where the dialog is theirs.
153
+ */
154
+ export declare function claudeStuckHook(options?: ClaudeStuckHookOptions): ClaudeStuckHookSettings;
155
+ /**
156
+ * What Claude Code wrote to a `Notification` hook when it opened its permission dialog: the
157
+ * session that waits, and what it shows. Undefined for any other input, other notifications
158
+ * included.
159
+ *
160
+ * @param hookInput what Claude Code wrote to the hook's stdin
161
+ */
162
+ export declare function claudeStuckCall(hookInput: string): {
163
+ caller: CallerIdentity;
164
+ what: string;
165
+ } | undefined;
166
+ /**
167
+ * What Claude Code wrote to a `PermissionRequest` hook, as a call to ask leave for: the session,
168
+ * the call, and how to answer Claude Code. Undefined for any other input.
169
+ *
170
+ * @param hookInput what Claude Code wrote to the hook's stdin
171
+ */
172
+ export declare function claudePermissionCall(hookInput: string): PermissionHookCall | undefined;
84
173
  /**
85
174
  * Where Claude Code has the bridge's server of tools for the sessions of a folder: `local`
86
175
  * (this person, this project), `project` (the project's `.mcp.json`) or `user` (this person,
@@ -107,7 +196,11 @@ export interface ClaudeCodeAdapterOptions {
107
196
  bridgeHome?: string;
108
197
  /** The environment of the commands and of the sessions it starts, `process.env` by default */
109
198
  env?: NodeJS.ProcessEnv;
110
- /** The permission mode of the sessions it starts, Claude Code's own default when absent */
199
+ /**
200
+ * The permission mode of the sessions it starts, `acceptEdits` by default: a session changes
201
+ * files in the folder of its job without asking, and asks leave through the bridge for the
202
+ * rest. `default` asks for every change too, `plan` lets it change nothing
203
+ */
111
204
  permissionMode?: string;
112
205
  /** More arguments for `claude --bg`, such as `['--model', 'sonnet']` */
113
206
  sessionArgs?: readonly string[];
@@ -1 +1 @@
1
- {"version":3,"file":"claude.d.ts","sourceRoot":"","sources":["../../src/adapters/claude.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"claude.d.ts","sourceRoot":"","sources":["../../src/adapters/claude.ts"],"names":[],"mappings":"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"}
@@ -2,7 +2,9 @@ import { readFileSync } from 'node:fs';
2
2
  import { homedir } from 'node:os';
3
3
  import { dirname, join, resolve } from 'node:path';
4
4
  import { z } from 'zod';
5
+ import { oneLine } from '../letters.js';
5
6
  import { canonicalPath, findProjectRoot } from '../paths.js';
7
+ import { describeAsk } from '../permit.js';
6
8
  import { TOOL_CALL_HINT_KEY } from '../tools/caller.js';
7
9
  import { HARNESSES } from '../types.js';
8
10
  import { CommandMissingError, failureOf, fitsArgument, pause, runCommand, sessionEnv, shellQuote, tooLongNotice, } from './exec.js';
@@ -152,6 +154,201 @@ const HookInputSchema = z.object({
152
154
  session_id: z.string().min(1),
153
155
  cwd: z.string().min(1).optional(),
154
156
  });
157
+ /** The command a hook of a Claude Code session runs to ask leave for a call through the bridge. */
158
+ export function claudePermitCommand(options = {}) {
159
+ const timeoutS = options.timeoutS ?? DEFAULT_HOOK_TIMEOUT_S;
160
+ return [
161
+ options.bridgeCommand ?? 'cogitator bridge',
162
+ 'permit',
163
+ `--hook ${HARNESSES.claudeCode}`,
164
+ `--timeout ${Math.max(1, Math.floor(timeoutS - HOOK_MARGIN_S))}`,
165
+ ...(options.agentName ? [`--agent ${shellQuote(options.agentName)}`] : []),
166
+ ...(options.bridgeHome ? [`--home ${shellQuote(options.bridgeHome)}`] : []),
167
+ ].join(' ');
168
+ }
169
+ /**
170
+ * The settings that make a Claude Code session ask leave through the bridge: a
171
+ * `PermissionRequest` hook, which Claude Code runs for every call its mode and rules would
172
+ * show the permission dialog for. The hook takes the call to the bridge and answers with the
173
+ * verdict. They are for a session the bridge starts, where nobody sits to answer the dialog: a
174
+ * session without them waits on its first dialog until its job fails. A session a person opened
175
+ * does not get them, the dialog there is the person's.
176
+ */
177
+ export function claudePermitHook(options = {}) {
178
+ return {
179
+ hooks: {
180
+ PermissionRequest: [
181
+ {
182
+ hooks: [
183
+ {
184
+ type: 'command',
185
+ command: claudePermitCommand(options),
186
+ timeout: Math.ceil(options.timeoutS ?? DEFAULT_HOOK_TIMEOUT_S),
187
+ },
188
+ ],
189
+ },
190
+ ],
191
+ },
192
+ };
193
+ }
194
+ /**
195
+ * The permission mode of a Claude Code session the bridge starts, unless the adapter is told
196
+ * another: edits inside the folder of the job need no leave, everything else goes by the rules
197
+ * of the project and, where they are silent, through the bridge.
198
+ */
199
+ export const CLAUDE_SESSION_MODE = 'acceptEdits';
200
+ /** What Claude Code calls the notification of an open permission dialog. */
201
+ const PERMISSION_PROMPT = 'permission_prompt';
202
+ /** Seconds the hook that says a session waits for a person may take. */
203
+ const STUCK_HOOK_TIMEOUT_S = 30;
204
+ /** The command a hook of a Claude Code session runs when the session waits for a person. */
205
+ export function claudeStuckCommand(options = {}) {
206
+ return [
207
+ options.bridgeCommand ?? 'cogitator bridge',
208
+ 'stuck',
209
+ `--hook ${HARNESSES.claudeCode}`,
210
+ ...(options.bridgeHome ? [`--home ${shellQuote(options.bridgeHome)}`] : []),
211
+ ].join(' ');
212
+ }
213
+ /**
214
+ * The settings that tell the bridge a Claude Code session waits for a person at its window: a
215
+ * `Notification` hook for permission prompts, which Claude Code runs when it opens its
216
+ * permission dialog. The hook runs in the background and decides nothing: it only lets the
217
+ * agent that handed the session a job know that the job stands still until a person answers.
218
+ * For the sessions a person opens, where the dialog is theirs.
219
+ */
220
+ export function claudeStuckHook(options = {}) {
221
+ return {
222
+ hooks: {
223
+ Notification: [
224
+ {
225
+ matcher: PERMISSION_PROMPT,
226
+ hooks: [
227
+ {
228
+ type: 'command',
229
+ command: claudeStuckCommand(options),
230
+ timeout: STUCK_HOOK_TIMEOUT_S,
231
+ async: true,
232
+ },
233
+ ],
234
+ },
235
+ ],
236
+ },
237
+ };
238
+ }
239
+ const NotificationInputSchema = z.object({
240
+ session_id: z.string().min(1),
241
+ cwd: z.string().min(1).optional(),
242
+ hook_event_name: z.literal('Notification'),
243
+ notification_type: z.string().optional(),
244
+ message: z.string().optional(),
245
+ });
246
+ /**
247
+ * What Claude Code wrote to a `Notification` hook when it opened its permission dialog: the
248
+ * session that waits, and what it shows. Undefined for any other input, other notifications
249
+ * included.
250
+ *
251
+ * @param hookInput what Claude Code wrote to the hook's stdin
252
+ */
253
+ export function claudeStuckCall(hookInput) {
254
+ let input;
255
+ try {
256
+ input = JSON.parse(hookInput);
257
+ }
258
+ catch {
259
+ return undefined;
260
+ }
261
+ const parsed = NotificationInputSchema.safeParse(input);
262
+ if (!parsed.success || parsed.data.notification_type !== PERMISSION_PROMPT)
263
+ return undefined;
264
+ const cwd = resolve(parsed.data.cwd ?? process.cwd());
265
+ return {
266
+ caller: {
267
+ harness: HARNESSES.claudeCode,
268
+ sessionId: parsed.data.session_id,
269
+ cwd,
270
+ project: findProjectRoot(cwd),
271
+ },
272
+ what: parsed.data.message?.trim() || 'Claude Code needs a permission',
273
+ };
274
+ }
275
+ const PermissionHookInputSchema = z.object({
276
+ session_id: z.string().min(1),
277
+ cwd: z.string().min(1).optional(),
278
+ permission_mode: z.string().min(1).optional(),
279
+ hook_event_name: z.literal('PermissionRequest'),
280
+ tool_name: z.string().min(1),
281
+ tool_input: z.record(z.string(), z.unknown()).optional(),
282
+ });
283
+ const EDIT_TOOLS = new Set(['Edit', 'Write', 'MultiEdit', 'NotebookEdit']);
284
+ const READ_TOOLS = new Set(['Read', 'Glob', 'Grep', 'LS']);
285
+ function textOf(value) {
286
+ return typeof value === 'string' && value.trim() !== '' ? value : undefined;
287
+ }
288
+ /** What a call of one of Claude Code's own tools touches, read from its input. */
289
+ function claudeAsk(tool, input, cwd) {
290
+ const name = oneLine(tool).slice(0, 256) || 'tool';
291
+ const path = textOf(input.file_path) ?? textOf(input.notebook_path) ?? textOf(input.path);
292
+ if (tool === 'Bash') {
293
+ const command = textOf(input.command);
294
+ if (command)
295
+ return { tool: name, access: 'command', command, cwd };
296
+ }
297
+ if (EDIT_TOOLS.has(tool) && path) {
298
+ return { tool: name, access: 'edit', paths: [resolve(cwd, path)] };
299
+ }
300
+ if (READ_TOOLS.has(tool)) {
301
+ return { tool: name, access: 'read', paths: [resolve(cwd, path ?? '.')] };
302
+ }
303
+ if (tool === 'WebFetch') {
304
+ const url = textOf(input.url);
305
+ if (url)
306
+ return { tool: name, access: 'fetch', url };
307
+ }
308
+ return { tool: name, access: 'other' };
309
+ }
310
+ /**
311
+ * What Claude Code wrote to a `PermissionRequest` hook, as a call to ask leave for: the session,
312
+ * the call, and how to answer Claude Code. Undefined for any other input.
313
+ *
314
+ * @param hookInput what Claude Code wrote to the hook's stdin
315
+ */
316
+ export function claudePermissionCall(hookInput) {
317
+ let input;
318
+ try {
319
+ input = JSON.parse(hookInput);
320
+ }
321
+ catch {
322
+ return undefined;
323
+ }
324
+ const parsed = PermissionHookInputSchema.safeParse(input);
325
+ if (!parsed.success)
326
+ return undefined;
327
+ const { session_id: sessionId, tool_name: tool, permission_mode: mode } = parsed.data;
328
+ const cwd = resolve(parsed.data.cwd ?? process.cwd());
329
+ const args = parsed.data.tool_input ?? {};
330
+ const ask = claudeAsk(tool, args, cwd);
331
+ const said = textOf(args.description);
332
+ return {
333
+ caller: {
334
+ harness: HARNESSES.claudeCode,
335
+ sessionId,
336
+ cwd,
337
+ project: findProjectRoot(cwd),
338
+ ...(mode && { permissionMode: oneLine(mode).slice(0, 256) }),
339
+ },
340
+ ask,
341
+ body: ask.access === 'other'
342
+ ? `${said ? `${said}\n` : ''}Call ${ask.tool} with ${JSON.stringify(args).slice(0, 2_000)}`
343
+ : describeAsk(ask, said),
344
+ answer: (verdict, reason) => JSON.stringify({
345
+ hookSpecificOutput: {
346
+ hookEventName: 'PermissionRequest',
347
+ decision: verdict === 'allow' ? { behavior: 'allow' } : { behavior: 'deny', message: reason },
348
+ },
349
+ }),
350
+ };
351
+ }
155
352
  const ListedSessionSchema = z.object({
156
353
  id: z.string().optional(),
157
354
  sessionId: z.string().optional(),
@@ -160,6 +357,8 @@ const ListedSessionSchema = z.object({
160
357
  pid: z.number().optional(),
161
358
  status: z.string().optional(),
162
359
  state: z.string().optional(),
360
+ /** What a session that waits is waiting for, such as `permission prompt` */
361
+ waitingFor: z.string().optional(),
163
362
  });
164
363
  const ServersSchema = z.record(z.string(), z.unknown()).optional();
165
364
  const TrustConfigSchema = z.object({
@@ -303,12 +502,13 @@ export function claudeCodeAdapter(options = {}) {
303
502
  const whole = fitsArgument(request.firstLetter.text);
304
503
  const tools = options.toolsServer;
305
504
  const waits = claudeWaitHook({ ...hook, agentName: request.agentName, tools: !!tools });
505
+ const permit = claudePermitHook({ ...hook, agentName: request.agentName });
306
506
  const settings = tools
307
507
  ? {
308
- hooks: { ...waits.hooks, ...claudeToolsHook(hook).hooks },
508
+ hooks: { ...waits.hooks, ...claudeToolsHook(hook).hooks, ...permit.hooks },
309
509
  permissions: { allow: [CLAUDE_TOOLS_PERMISSION] },
310
510
  }
311
- : waits;
511
+ : { hooks: { ...waits.hooks, ...permit.hooks } };
312
512
  const servers = tools && {
313
513
  mcpServers: {
314
514
  [BRIDGE_TOOLS_SERVER]: {
@@ -328,7 +528,8 @@ export function claudeCodeAdapter(options = {}) {
328
528
  '--settings',
329
529
  JSON.stringify(settings),
330
530
  ...(request.sessionName ? ['--name', request.sessionName] : []),
331
- ...(options.permissionMode ? ['--permission-mode', options.permissionMode] : []),
531
+ '--permission-mode',
532
+ options.permissionMode ?? CLAUDE_SESSION_MODE,
332
533
  ...(options.sessionArgs ?? []),
333
534
  whole
334
535
  ? request.firstLetter.text
@@ -390,6 +591,7 @@ export function claudeCodeAdapter(options = {}) {
390
591
  ...(session.cwd && { cwd: session.cwd }),
391
592
  ...(session.name && { name: session.name }),
392
593
  ...(session.status && { busy: session.status === 'busy' }),
594
+ ...(session.waitingFor && { waitingFor: session.waitingFor }),
393
595
  },
394
596
  ]
395
597
  : []);
@@ -531,6 +733,8 @@ export function claudeCodeAdapter(options = {}) {
531
733
  liveSessions,
532
734
  identify,
533
735
  toolCallHook,
736
+ permissionHook: (context) => context.hookInput === undefined ? undefined : claudePermissionCall(context.hookInput),
737
+ stuckHook: (context) => context.hookInput === undefined ? undefined : claudeStuckCall(context.hookInput),
534
738
  health,
535
739
  };
536
740
  }