@bondsmith/bondsmithd 0.1.14 → 0.1.16

package/README.md

@@ -82,20 +82,20 @@ that pane belongs to:
 tmux set-option -t "$TMUX_PANE" -q @bondsmith-agent-state "waiting:$(date +%s)"
 ```
 
-The value is `<state>:<epoch seconds>`, where state is `working`, `waiting` (needs the user) or `done`.
+The value is `<state>:<epoch seconds>`, where state is `working`, `waiting` (needs the user) or `done` (finished a turn, shown until the user attaches, types or resizes after it).
 The daemon reads it on its 5-second tick and shows it on the session. Anything else is ignored, as is
 a report dated in the future. A `waiting` or `done` report is dropped once the pane writes output more
 than 2 seconds after it, since that means the agent moved on. A `working` report is dropped once the
 pane has been silent for 2 minutes, since an interrupted or crashed agent never reports again.
 
 Claude Code sessions that Bondsmith starts as plain `claude` report this on their own (see the end of the
-plan section below): `working` when a prompt is sent, `waiting` when it asks for permission, finishes a
-turn or fails with an API error. Nothing needs installing for those.
+plan section below): `working` when a prompt is sent, `waiting` when it asks for permission or fails with
+an API error, `done` when it finishes a turn. Nothing needs installing for those.
 
 For an agent the daemon does not set up (a wrapper, `npx claude`, another agent), note that every session
 Bondsmith starts has `BONDSMITH_SESSION` set to its id, so a hook installed once for all your projects can
 stay silent everywhere else. This entry in `~/.claude/settings.json` reports a Claude Code session as
-waiting the moment it asks for permission or finishes a turn:
+waiting the moment it asks for permission, and as done when it finishes a turn:
 
 ```json
 {
@@ -116,7 +116,7 @@ waiting the moment it asks for permission or finishes a turn:
 				"hooks": [
 					{
 						"type": "command",
-						"command": "[ -n \"$BONDSMITH_SESSION\" ] && tmux set-option -t \"$TMUX_PANE\" -q @bondsmith-agent-state \"waiting:$(date +%s)\"; exit 0"
+						"command": "[ -n \"$BONDSMITH_SESSION\" ] && tmux set-option -t \"$TMUX_PANE\" -q @bondsmith-agent-state \"done:$(date +%s)\"; exit 0"
 					}
 				]
 			}
@@ -127,7 +127,7 @@ waiting the moment it asks for permission or finishes a turn:
 
 This is optional, and nothing edits your settings for you. The command does nothing outside a Bondsmith
 session, and sessions started before the daemon set the variable are skipped by it. It reports only
-`waiting`. A `working` report is dropped after the pane has been silent for 2 minutes, so one that an
+`waiting` and `done`. A `working` report is dropped after the pane has been silent for 2 minutes, so one that an
 interrupted Claude Code never clears (it does not run `Stop` then, and has no hook for Escape) expires on
 its own.
 
@@ -143,24 +143,25 @@ A hook can store the plan outside the repository instead, in `~/.bondsmith/plans
 option, so a plan written there is never left over from an earlier session.
 
 For Claude Code the daemon sets this up itself. When a session's command is `claude` (that word alone, not
-behind `npx`, an environment variable or a wrapper), the daemon starts it as
+behind `npx` or a wrapper; `VAR=value` words before it are fine), the daemon starts it as
 `claude --settings ~/.bondsmith/hooks/claude-settings.json …`. That file adds hooks to the ones you
-already have: after you approve a plan in plan mode, one stores the plan as above, and four report the agent
-state (`working` on a prompt; `waiting` on a permission request, the end of a turn, or a turn that fails with
+already have: one stores the plan as above as soon as plan mode proposes it, before you approve it;
+another logs the agent's task calls (`TaskCreate`, `TaskUpdate`, `TodoWrite`) to `~/.bondsmith/plans/<session id>.tasks.jsonl`,
+which the daemon replays into the session's task list (shown under the plan in the browser); and four
+report the agent state (`working` on a prompt; `waiting` on a permission request, the end of a turn, or a turn that fails with
 an API error). Nothing in `~/.claude` changes, the session still shows the command you typed, and the hooks
 do nothing outside a Bondsmith session. Claude Code's `/hooks` menu does not list hooks passed with
 `--settings`, though they run.
 
-A fifth hook stores the latest prompt as the session's headline, which the sessions list and the session bar
-show. It is the prompt on one line, cut at 200 characters, in the tmux option `@bondsmith-headline`. A reply
-that only answers the agent (`yes`, `continue`, `ok`, `thanks`, and a few like them) or a prompt under 4
-characters leaves the earlier headline in place; a built-in slash command such as `/help` sends no prompt to
-the hook, so it does too. The prompt is stored as typed, so a secret in a prompt is in the headline.
+A fifth hook watches Bash calls for `gh pr create`. When one succeeds and prints a pull request URL, the URL is
+appended to the tmux option `@bondsmith-prs` (space separated, each once, the newest 20 kept), and the daemon
+reports it on the session as `pullRequestUrls`. It matches `gh pr create` only as a command of its own, so
+`echo "gh pr create"` or `gh pr view` record nothing, and a failed command never reaches it.
 
 The daemon leaves the command alone if it already has `--settings`, if the installed `claude` does not list
 `--settings` in `claude --help` (asked once per daemon run; if `claude` cannot be run at all, that is logged
 and asked again after a minute), or if `BONDSMITH_AGENT_HOOKS` is set to `off`, `0`, `false` or `no` where
-the daemon starts. Each hook has a timeout (5 seconds for a state report or the headline, 10 for the plan), so a stuck command
+the daemon starts. Each hook has a timeout (5 seconds for a state report, 10 for the plan and the task list), so a stuck command
 cannot hold up the agent. Plans are written to `~/.bondsmith/plans` readable only by you, and a symlink in
 the way is replaced, not followed. A plan the agent changes later without going back through plan mode is
 not seen; the hook's plan keeps winning over the folder's file until the next approval.
@@ -204,6 +205,33 @@ tmux only flags a bell when no client is attached to the session or the bell is
 the one the attached client has open. A session whose terminal is open in a browser tab, even a hidden
 one, counts as being looked at, so a bell in it is not flagged; use the hook report for that case.
 
+## Adding an agent
+
+The daemon splits what is the same for every agent from what is one agent's own.
+
+| Part                                                                                                                    | Where                                                                  | Agent-specific?   |
+| ----------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- | ----------------- |
+| What an agent reports: state, plan, task list, pull requests (the channels below)                                       | `src/sessions/agent-reports/`                                          | No                |
+| Turning reports into what the UI shows (`readSessionReport`: the plan and the task list for `getPlan`; attention state) | `agent-reports/`, `tmux/agent-state.ts`                                | No                |
+| Recognising an agent's command and launching it so it reports                                                           | `src/sessions/agents/<agent>/`                                         | Yes               |
+| The list of agents                                                                                                      | `AGENT_IDS` in `@bondsmith/local-agent-protocol`; `agents/registry.ts` | Add one line each |
+
+An agent reports through these channels, and the daemon reads them without caring who wrote them:
+
+| Report        | Channel                                                                                                                                                                     |
+| ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| State         | tmux option `@bondsmith-agent-state` = `<working\|waiting\|done>:<epoch seconds>` on the session's pane; or ring the bell; or nothing (a pane gone quiet counts as waiting) |
+| Plan          | `~/.bondsmith/plans/<session id>.md`, or `.bondsmith/plan.md` in the session's folder, or tmux option `@bondsmith-plan`                                                     |
+| Task list     | `~/.bondsmith/plans/<session id>.tasks.jsonl`: one JSON `TaskEvent` per line, appended (`add`, `update`, `remove`, `replace`; see `agent-reports/task-list.ts`)             |
+| Pull requests | tmux option `@bondsmith-prs`, space-separated URLs                                                                                                                          |
+
+To add an agent: add its id to `AGENT_IDS`, which makes `registry.ts` refuse to compile until it has an adapter. A new
+`AgentAdapter` needs `matches(command)` and `prepareCommand(command)`. With nothing to set up use `plainAdapter(id)`,
+as Codex and opencode do today (they report through the bell and the quiet-pane check). With hooks, put the agent's
+settings and payload mapping in `agents/<agent>/` and build its hook commands from the helpers in
+`agent-reports/hook-commands.ts` and `agent-reports/hook-scripts.ts`; the agent's file only says where in its
+payload the plan, the task event and the shell command are. `agents/claude/` is the worked example.
+
 ## Production connectivity (current status)
 
 `bondsmithd` connects outbound to the Bondsmith relay by default (`BONDSMITH_RELAY_ENABLED=true`,