@bondsmith/bondsmithd 0.1.15 → 0.1.17

package/README.md

@@ -143,21 +143,17 @@ 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 sixth hook watches Bash calls for `gh pr create`. When one succeeds and prints a pull request URL, the URL is
+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.
@@ -165,7 +161,7 @@ reports it on the session as `pullRequestUrls`. It matches `gh pr create` only a
 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.
@@ -209,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`,