make pi the only harness, drop Claude Code support entirely
Removed AGENT_KIND/DIWAN_HARNESS and CLAUDE_PERMISSION_MODE/ DIWAN_PERMISSION_MODE; herdr_agent_start_args now hardcodes --kind pi and always appends PI_APPROVE_FLAG. Motivated by a real live failure: Claude Code blocks on an interactive first-run trust dialog in any content repo it hasn't seen before, which herdr's real-pane dispatch can't answer (agent_not_ready after a 30s timeout). pi has no such dialog and no per-tool-call approval gate, so it was already the better fit for diwan's unattended model -- confirmed live against a brand-new content repo with zero blocking. Updated PROTOCOL.md/DESIGN.md accordingly, replacing the harness- agnosticism framing with an explicit pi-only statement, while leaving TICK.md/DO.md untouched since neither ever mentioned a specific harness.
This commit is contained in:
1 parent
d52f733f14
commit
18c8284349
3 files changed
+23
-33
No files matched your search
@@ -8,7 +8,7 @@ diwan is an AI layer over a plain org-mode "second brain" (notes, tasks, calenda
|
||||
|
||||
**This repo is diwan the tool, and nothing else.** It contains the CLI and the generic procedure docs (`PROTOCOL.md`, `TICK.md`, `DO.md`) — no personal notes, no content-repo-specific convention docs. It's meant to be installed independently (on `PATH`, eventually via its own nix flake) and pointed at *any* notes repo. Marc's actual notes live in `~/nc/org-agenda` (the real, continuously-synced data) and, for development/testing, in a throwaway sibling repo `diwan-dev-notes` (a git-tracked fixture copy, safe to break). Neither of those repos contains any of diwan's own code or docs — see "Known gaps" for exactly how far that packaging currently goes.
|
||||
|
||||
Status as of this writing: the core loop (tick → triage/dispatch, do → delegated work, both via real herdr sessions) is built and has been exercised end-to-end against live `herdr` and `claude`. The tool/content split (this repo vs. `diwan-dev-notes`) happened 2026-11-09, right after that verification — see "Known gaps" for what that split still owes a fresh live pass on.
|
||||
Status as of this writing: the core loop (tick → triage/dispatch, do → delegated work, both via real herdr sessions) is built and has been exercised end-to-end against live `herdr`. The tool/content split (this repo vs. `diwan-dev-notes`) happened 2026-11-09, and the harness was narrowed to `pi` exclusively right after that (dropping Claude Code support entirely) — see "Known gaps" for what both of those still owe a fresh live pass on.
|
||||
|
||||
## Principles (why things are shaped this way)
|
||||
|
||||
@@ -18,7 +18,7 @@ These were distilled from how Marc already works and what he explicitly asked fo
|
||||
2. **Act first, review passively.** No per-edit approval gate — every action is reported and trivially revertable instead.
|
||||
3. **Mechanism over magic.** Small, inspectable, deterministic steps over one opaque "agent did something" blob — Marc wants to be able to understand a failure well enough to jump in personally.
|
||||
4. **Grow by accretion.** Ship the smallest loop that works; add complexity only once the simpler version has been lived with. (Concretely: v0 has no custom CLI-level org-tag manipulation, no scheduler, no kill-on-timeout logic — these are deliberately not yet built.)
|
||||
5. **Harness as a thin, swappable shell.** The procedure (what tick/do should do) and the primitives (how edits actually happen) are decoupled from which LLM product is driving. Claude Code today; `pi` is a supported herdr integration kind and should work by just changing `DIWAN_HARNESS`.
|
||||
5. **One harness, chosen deliberately: `pi`.** diwan dispatches `pi` and only `pi` — not a pluggable choice. Claude Code was the original harness and worked, but needed `--permission-mode auto` to avoid prompting for approval on every tool call, and blocks on an interactive first-run trust dialog that herdr's real-pane dispatch can't answer (hit live 2026-11-09 against the fresh `diwan-dev-notes` content repo). `pi` has no per-tool-call approval gate and no such trust dialog (only a one-time, non-interactive-safe project-trust decision for protected `.pi/*` resources, handled by `--approve`) — it was built to run unattended from the start, which is exactly diwan's own model. The procedure docs (`TICK.md`/`DO.md`) still don't hardcode anything pi-specific into their wording, as a matter of good practice, but there's no expectation of swapping harnesses again.
|
||||
6. **Two symmetric channels, one substrate.** Talk to diwan via the notes (`:chat:`) or via the live herdr session — both write to the same git-tracked truth.
|
||||
7. **Mobile stays dumb.** Nothing new to install on the phone.
|
||||
8. **Tool and content are separate repos.** diwan the tool (this repo) ships independent of any one person's notes; a content repo (e.g. `diwan-dev-notes`, or Marc's real `~/nc/org-agenda`) only ever contains notes, `AGENTS.md`, `diwan.org`, and diwan's own tiny `.diwan/` runtime-bookkeeping directory (`state.json`, `.lock`) — never the CLI or the procedure docs. This is what makes the content repo distributable (synced via Nextcloud to a server, edited from beorg) without dragging a whole dev tool along with it, and what keeps diwan's own generic contract reviewable/versionable independent of any one person's data.
|
||||
@@ -31,7 +31,7 @@ Three layers, each independently simple:
|
||||
- **herdr**, a terminal-multiplexer-for-agents with a JSON-over-socket CLI (`herdr workspace/tab/pane/agent ...`). diwan doesn't invent a session store: one herdr workspace labeled `diwan` holds every tick run and every open `do` session as a separate, independently addressable, persistent tab. See "herdr integration" below for the exact calls.
|
||||
- **The `diwan` CLI** (`./diwan` at this repo's root), a single dependency-free Python script (shebang runs it through `nix shell nixpkgs#python3`, so no system Python install needed on NixOS; a real flake package would wrap this properly instead). It does only the mechanical, deterministic parts: git bookkeeping, enough org parsing to read/write a `DIWAN_ID` property and insert a `Close diwan session` checkbox item, and herdr dispatch. It never triages, writes prose, or makes judgment calls — that's the dispatched agent's job, guided by `TICK.md`/`DO.md`. It distinguishes two roots explicitly (see the script's own docstring): `DIWAN_DIR` (where it and its docs are installed — `Path(__file__).resolve().parent`, overridable via the `DIWAN_DIR` env var for whatever a future flake's install layout needs) and `DIWAN_NOTES_DIR` (whatever notes repo it's invoked against, found via `git rev-parse --show-toplevel` from the current directory by default, overridable via the `DIWAN_NOTES_DIR` env var for e.g. a cron/systemd timer that doesn't cd into it first). `diwan` must be run from inside (or below) a content repo, or have `DIWAN_NOTES_DIR` set — it has no content of its own to act on.
|
||||
|
||||
Everything else (what counts as "trivial", where an inbox item belongs, how to answer a chat question) is intentionally **not** code — it's prose in `TICK.md`/`DO.md` that whatever LLM is dispatched has to interpret. This is the harness-agnosticism principle made concrete: the CLI's job ends at "here's a prompt, here's a terminal," everything judgment-shaped is left to the model.
|
||||
Everything else (what counts as "trivial", where an inbox item belongs, how to answer a chat question) is intentionally **not** code — it's prose in `TICK.md`/`DO.md` that the dispatched `pi` agent has to interpret. The CLI's job ends at "here's a prompt, here's a terminal"; everything judgment-shaped is left to the model.
|
||||
|
||||
## Doc map
|
||||
|
||||
@@ -66,7 +66,7 @@ Note what's *not* here: `last_tick_commit` is deliberately **not** updated by th
|
||||
4. Write one short, titled, checkbox subheading per notable thing this run did into `diwan.org`'s Reports log (not one paragraph for the whole run), each with an optional `:LINK:` property and a 1-2 line signed body; delete any already-`[X]` subheadings first.
|
||||
5. Only if 1–4 all succeeded: update `state.json.last_tick_commit` to current `HEAD` and commit under the diwan identity.
|
||||
|
||||
**Verified live** (2026-11-08, herdr 0.9.5 + Claude Code, `claude` kind, against the old mixed tool+content repo, before the 2026-11-09 split): dispatched for real, ran to completion with zero permission prompts (see "Known gaps" for why that almost didn't work), correctly left two already-open `:session:`-tagged sessions untouched (back when `:session:` was still spelled `:diwan:`, before the tag rename — see "Known gaps" for what's unverified post-rename), correctly found nothing to triage, wrote a proper signed report, and updated `state.json` correctly. A second immediate `diwan tick` correctly no-op'd. **Not yet re-verified with a real dispatched agent** against the post-split layout (tool repo + separate `diwan-dev-notes` content repo, `DIWAN_DIR`/`DIWAN_NOTES_DIR` as two different directories) — path resolution itself has been dry-run tested (see below), but no agent has actually followed the resulting prompt yet. See "Known gaps".
|
||||
**Verified live** (2026-11-08, herdr 0.9.5 + Claude Code, before both the 2026-11-09 tool/content split and the pi-only harness switch): dispatched for real, ran to completion with zero permission prompts, correctly left two already-open `:session:`-tagged sessions untouched (back when `:session:` was still spelled `:diwan:`, before the tag rename — see "Known gaps" for what's unverified post-rename), correctly found nothing to triage, wrote a proper signed report, and updated `state.json` correctly. A second immediate `diwan tick` correctly no-op'd. **Not yet re-verified with a real dispatched agent** against the current state of things (post-split two-repo layout, `pi` as the sole harness) — path resolution and `pi`'s own startup have each been tested separately (see below and "Known gaps"), but not yet together through a full live tick run. Do that before trusting it for real.
|
||||
|
||||
## What `diwan do` actually does
|
||||
|
||||
@@ -84,9 +84,9 @@ Same split: `cmd_do` (CLI) decides identity/dispatch mechanics; `DO.md` governs
|
||||
|
||||
**Agent half** (`DO.md`): stay inside your own heading's subtree; if something needs doing elsewhere, ask in `:chat:` rather than reaching out of scope (cross-cutting work like this is now `tick`'s job to do directly, per the `:diwan:` tag section — don't try to talk another `do` session into doing it either); use the chat protocol for questions/FYIs; commit progress in small units under the diwan identity through the flock-wrapped recipe; never touch your own `Close diwan session` item — that's Marc's call, acted on by the next tick. One explicit exception to subtree-only: a `do` agent may append its own entry to `diwan.org`'s Reports log once it finishes something worth telling Marc about, since that's its only channel to him outside of a tick run — it still never edits or deletes an existing entry there, only `tick` does that. A tick that merely nudges an idle session (see `cmd_tick` step 3 above) does not report the nudge itself — it has no idea yet whether anything came of it.
|
||||
|
||||
**Verified live** (against the old mixed repo, pre-split): dispatched for real against the "gather info about Greece trip" heading. Did real web research, wrote a structured result into the heading, correctly asked clarifying questions via a signed `:chat:` entry instead of guessing, left `Close diwan session` untouched, committed as `diwan <diwan@local>` with a descriptive message.
|
||||
**Verified live with Claude Code** (pre tool/content split, pre pi-only switch): dispatched for real against the "gather info about Greece trip" heading. Did real web research, wrote a structured result into the heading, correctly asked clarifying questions via a signed `:chat:` entry instead of guessing, left `Close diwan session` untouched, committed as `diwan <diwan@local>` with a descriptive message. (Historical — Claude Code is no longer a supported harness; see "One harness, chosen deliberately" above.)
|
||||
|
||||
**`pi` kind, verified live** (2026-11-08, herdr 0.9.5 + pi 1.5.0, pre-split): ad-hoc `diwan do "<prompt>" --diwan-id pi-smoketest` with `DIWAN_HARNESS=pi` correctly started a herdr `pi` agent (detected as `agent: "pi"`, no trust/approval prompt blocked it, confirming `--approve` is doing its job with no protected `.pi/*` resources in that repo to actually gate), loaded `AGENTS.md` as context the way `claude` does, and replied exactly as instructed. A second `diwan do` call against the same `--diwan-id` reused the same pane/tab and agent (continuation dispatch, not a fresh one) and replied correctly again. Not yet exercised: a real `tick` or `do` run against actual heading content with `DIWAN_HARNESS=pi` (only ad-hoc free-text prompts so far) — same caveat as any first integration, worth a full pass before relying on it for real delegated work.
|
||||
**`pi`, verified live, ad-hoc dispatch only** (2026-11-08, herdr 0.9.5 + pi 1.5.0, pre-split; re-confirmed 2026-11-09 post-split, post-switch against the fresh `diwan-dev-notes` repo): `diwan do "<prompt>" --diwan-id <id>` correctly starts a herdr `pi` agent (detected as `agent: "pi"`), with no trust/approval prompt blocking it even in a content repo `pi` had never seen before (confirming it really doesn't share Claude Code's first-run trust-dialog problem — see "Known gaps"), loads `AGENTS.md` as context, and replies exactly as instructed. A second `diwan do` call against the same `--diwan-id` reuses the same pane/tab and agent (continuation dispatch, not a fresh one) and replies correctly again. **Not yet exercised**: a real `tick` or `do` run against actual heading content with `pi` as the agent (only ad-hoc free-text prompts so far) — worth a full pass before relying on it for real delegated work.
|
||||
|
||||
## `DIWAN_ID` ⇄ herdr, precisely
|
||||
|
||||
@@ -100,9 +100,8 @@ Lifecycle: **fresh** (no property) → `diwan do` mints an ID, creates the tab+a
|
||||
- **No flake yet.** The split prepared the ground (tool repo is self-contained, no content-repo assumptions baked into its own files) but there's no `flake.nix` in this repo yet, and the shebang still runs via a bare `nix shell nixpkgs#python3` rather than a proper package. Until that lands, "installed on `PATH`" means manually symlinking/aliasing `diwan` somewhere on `PATH` yourself. `DIWAN_DIR` exists specifically so a future flake's install layout (e.g. docs copied into `$out/share/diwan/` alongside a wrapped binary) can override the default `Path(__file__).resolve().parent` guess if it doesn't hold.
|
||||
- **Retired-session teardown.** `TICK.md` step 3 says a closed session has "nothing for you to do to the heading's content" and that herdr-side teardown "is not your job" — but nothing else currently closes that tab either. Right now a `Close diwan session` checked off (`[X]`) just... sits there, tab still open. This is a real gap, not yet decided whether the CLI should gain a path for it or whether `TICK.md` should just say to run `herdr tab close` directly.
|
||||
- **No real conversation continuity across resumption.** Covered above — intentional for now, but worth revisiting if resumed `do` sessions turn out to need more context than the heading text carries.
|
||||
- **`pi` kind is wired up and smoke-tested, but not yet exercised against real heading content.** `DIWAN_HARNESS=pi` gets its own equivalent of the Claude autonomy flag (`--approve`, see "`pi` kind, verified live" above) and has been confirmed live for ad-hoc `diwan do` dispatch and continuation. Still untested: `diwan tick` with `DIWAN_HARNESS=pi`, and `diwan do` against a real `<file>:<line>` heading (DIWAN_ID minting, `:chat:` protocol, scope discipline) rather than a free-text ad-hoc prompt.
|
||||
- **`diwan.org`'s `Config` heading is a placeholder, not wired up.** PROTOCOL.md documents an intended home for configuration values governing diwan's own behavior (tick cadence, tab retention, harness choice), but the CLI reads none of it — the env vars (`DIWAN_HARNESS`, `DIWAN_PERMISSION_MODE`, `DIWAN_PI_APPROVE`, `DIWAN_MAX_TICK_TABS`) remain the only real knobs. Don't assume anything in that heading does something until the CLI actually reads it.
|
||||
- **`pi` is smoke-tested for ad-hoc dispatch, but not yet exercised against real heading content.** `--approve` has been confirmed live for ad-hoc `diwan do` dispatch and continuation, including against a content repo `pi` had never run in before (no trust-dialog block, unlike Claude Code — see "One harness, chosen deliberately" above). Still untested: a real `diwan tick` run, and `diwan do` against a real `<file>:<line>` heading (DIWAN_ID minting, `:chat:` protocol, scope discipline) rather than a free-text ad-hoc prompt.
|
||||
- **`diwan.org`'s `Config` heading is a placeholder, not wired up.** PROTOCOL.md documents an intended home for configuration values governing diwan's own behavior (tick cadence, tab retention, that kind of thing), but the CLI reads none of it — the env vars (`DIWAN_DIR`, `DIWAN_NOTES_DIR`, `DIWAN_PI_APPROVE`, `DIWAN_MAX_TICK_TABS`) remain the only real knobs. Don't assume anything in that heading does something until the CLI actually reads it.
|
||||
- **The `:diwan:`/`:session:`/`:chat:` tag split, and tick doing cross-cutting maintenance directly, is new and unverified live.** Before this split, `:diwan:` alone meant what `:session:` means now, and anything non-trivial got a dedicated `do` session regardless of whether the work was subtree-shaped or genuinely repo-wide — which is exactly what motivated the split (a real `do` session hit the subtree wall trying to do an archive/cleanup/folder-move task). No tick run has yet exercised the new three-way decision in `TICK.md` step 3 (inline / `:session:` dispatch / tick-direct), the tag-consistency backfill in step 2, or tick actually doing a multi-file maintenance job itself across one or more runs — worth a close look at the first few real runs that hit this path.
|
||||
- **`--permission-mode auto` is a real autonomy decision, not a default to take for granted.** Dispatched agents run with Claude Code's own judgment-based auto mode (chosen over a full `--dangerously-skip-permissions` bypass, which Claude's docs scope to no-internet sandboxes — diwan agents do real web research). Override via `DIWAN_PERMISSION_MODE` env var. If this is ever revisited, it should be a deliberate conversation, not a silent change.
|
||||
- **Concurrency is scope discipline, not real locking**, beyond the git-commit flock. Two `do` agents editing truly disjoint subtrees should be fine; nothing stops two agents editing the *same* subtree if the scope rule is violated. There's no enforcement, only convention (PROTOCOL.md).
|
||||
- **No automated tests.** Everything described as "verified live" above was exercised by hand against a real herdr+claude install. There is no regression suite — a future session changing `diwan` should re-run at least the manual smoke tests (tick no-op gate, tick dispatch, do fresh dispatch, do continuation, a deliberately-invalid `DIWAN_ID`) before trusting a change.
|
||||
- **No automated tests.** Everything described as "verified live" above was exercised by hand against a real herdr install. There is no regression suite — a future session changing `diwan` should re-run at least the manual smoke tests (tick no-op gate, tick dispatch, do fresh dispatch, do continuation, a deliberately-invalid `DIWAN_ID`) before trusting a change.
|
||||
Reference in new issue
Block a user