@clearlysh/beehaven 0.8.34 → 0.8.35

package/dist/agents-md-text.js

@@ -1,64 +1,80 @@
 /**
  * agents-md-text — the Clearly block for a PROJECT's AGENTS.md, as `beehaven agents-md` writes it
- * (CAN2-66).
+ * (CAN2-66, AWO-401).
  *
  * ⚠⚠ A COPY, PINNED. The source of truth is the monorepo's `lib/connections/agentsMd.ts`, which the
- * Integrations page, each agent's details and the MCP `clearly-agents-md` prompt render. This
- * package cannot import it (it ships on its own), so the text is repeated here and the monorepo's
- * `lib/__tests__/agentsMdCliParity.test.mjs` compares the two OUTPUTS, name argument included.
- * Change both or the test fails — a stale copy does not render wrong, it instructs wrong.
+ * Integrations page, each agent's details, the /cli and /mcp guides and the MCP `clearly-agents-md`
+ * prompt render. This package cannot import it (it ships on its own), so the text is repeated here
+ * and the monorepo's `lib/__tests__/agentsMdCliParity.test.mjs` compares the two OUTPUTS, name
+ * argument included. Change both or the test fails — a stale copy does not render wrong, it
+ * instructs wrong.
+ *
+ * ⚠ ONE TRACKED BLOCK FOR MCP AND THE CLI (founder 2026-10-28): every task is tracked in Clearly,
+ * and each step names the MCP tool and the CLI command. The per-route blocks before it are removed
+ * when this one is written (`LEGACY_BLOCK_MARKERS`).
  *
  * ⚠ NO IMPORTS, so that test can load this file directly.
  */
-export const CLI_BLOCK_START = '<!-- clearly:cli:start -->';
-export const CLI_BLOCK_END = '<!-- clearly:cli:end -->';
-export const MCP_BLOCK_START = '<!-- clearly:mcp:start -->';
-export const MCP_BLOCK_END = '<!-- clearly:mcp:end -->';
+export const AGENTS_MD_START = '<!-- clearly:start -->';
+export const AGENTS_MD_END = '<!-- clearly:end -->';
+/** The per-route markers used before AWO-401. Writers remove these blocks; nothing writes them. */
+export const LEGACY_BLOCK_MARKERS = [
+    ['<!-- clearly:cli:start -->', '<!-- clearly:cli:end -->'],
+    ['<!-- clearly:mcp:start -->', '<!-- clearly:mcp:end -->'],
+];
+/** How Claude Code runs the MCP server's `clearly-agents-md` prompt, which writes the block. */
+export const MCP_AGENTS_MD_SLASH = '/mcp__clearly__clearly-agents-md';
 /** What goes in CLAUDE.md so Claude Code reads the AGENTS.md block too. */
 export const CLAUDE_MD_IMPORT = '@AGENTS.md';
-/** The block for agents that use the `beehaven` CLI. */
-export function agentsMdCliBlock(agentName) {
+/** Where the block goes, said once for every surface. */
+export const AGENTS_MD_HOW = 'Every agent that opens the repository reads AGENTS.md, so the block makes each session track its work in Clearly. Claude Code reads CLAUDE.md — give it one line.';
+/** The MCP tools the block names. Each must be on the server's `tools/list` (a Worker test pins it). */
+export const MCP_BLOCK_TOOLS = ['clearly_catalog', 'clearly_read', 'clearly_grep', 'clearly_create', 'clearly_edit', 'clearly_comment'];
+/**
+ * The block. `agentName` personalises the CLI sign-in line for one agent (its details view);
+ * without it the agent is told to use its own name.
+ */
+export function agentsMdBlock(agentName) {
     const name = (agentName ?? '').trim();
     const login = name
-        ? `\`beehaven agent login ${name} --label "<what you are doing>"\` — you are ${name} in this workspace.`
-        : '`beehaven agent login <name> --label "<what you are doing>"`, using your own name (claude, codex, gemini).';
+        ? `\`beehaven agent login ${name} --label "<the task>"\` — you are ${name} in this workspace —`
+        : '`beehaven agent login <your-name> --label "<the task>"` (claude, codex, gemini…)';
     return [
-        CLI_BLOCK_START,
-        '<!-- managed-by: clearly. Run `beehaven agents-md` to update; edit outside this block. -->',
+        AGENTS_MD_START,
+        '<!-- managed-by: clearly. Run `beehaven agents-md` or the `clearly-agents-md` MCP prompt to update; edit outside this block. -->',
         '',
-        '## Clearly workspace',
+        '## Clearly workspace: track every task',
         '',
-        'This project keeps its documents, plans, boards and tickets in Clearly. Use the `beehaven` CLI',
-        'for anything the team should see, not files in this repo.',
+        "This project's plans, tickets, documents and designs live in Clearly. Track every task there,",
+        'even when the person does not ask. Use whichever route this session has: the `clearly_*` MCP tools,',
+        "or the `beehaven` CLI (`beehaven actions` lists actions; `beehaven call <action> '<json>'` runs one).",
         '',
-        `- Sign in once per session: ${login}`,
+        '### Start of every session',
+        '',
+        `- CLI: sign in first with ${login} and read the brief it prints.`,
         '  If it says the daemon is not running: `beehaven start --headless`.',
-        '- Read the `clearly-agent` skill before anything else, and `clearly-canvas` before design work',
-        '  (`beehaven skills install` puts them in place).',
-        '- `beehaven actions` lists what you can call; `beehaven call <action> \'<json>\'` calls it.',
-        '- Search before you create, file work in the project it belongs to, and end the session with',
-        '  `beehaven agent handoff "what you did · what is next"` so the next one starts there.',
-        CLI_BLOCK_END,
-    ].join('\n');
-}
-/** The block for agents connected over MCP (the `clearly` server). */
-export function agentsMdMcpBlock() {
-    return [
-        MCP_BLOCK_START,
-        '<!-- managed-by: clearly-mcp. Re-run the `clearly-agents-md` prompt to update; edit outside this block. -->',
+        '  MCP: you are already signed in as the agent chosen when Clearly was connected.',
+        "- Read this project's open tickets and its latest handoff before starting (`clearly_grep` /",
+        '  `clearly_read`, or the brief).',
+        '',
+        '### Every task has a ticket',
+        '',
+        '1. Search first (`clearly_grep`, `clearly_catalog`, or `beehaven call ticket-list`). Reuse the project,',
+        '   board and ticket that already own the work; create a board only if the project has none.',
+        '2. Create the ticket before changing code or files (`clearly_create` with `type: "ticket"` and',
+        '   `fields.boardId`, or `beehaven call ticket-create`). Say in its body what done means.',
+        '3. Move it to in-progress when work begins (`clearly_edit`, or `beehaven call ticket-update`).',
+        '4. File what you make (documents, designs, notes) into the project and link it from the ticket.',
+        '   Record decisions, open questions and progress as comments (`clearly_comment`).',
+        '5. Mark it done only after verifying the result, with the resolution and any remaining risk.',
         '',
-        '## Clearly workspace (connected over MCP as `clearly`)',
+        '### End of every session',
         '',
-        'This project keeps its documents, plans, boards and tickets in Clearly. Use the `clearly_*`',
-        'tools, not files in this repo, for anything the team should see.',
+        '- Leave a handoff: what you did and what is next. CLI: `beehaven agent handoff "<done · next>"`.',
+        '  MCP: a comment on the work ticket.',
         '',
-        '- Start with `clearly_catalog` to see what exists; search with `clearly_grep` / `clearly_glob`.',
-        '- Read with `clearly_read`, make new work with `clearly_create`, change it with `clearly_edit`,',
-        '  and discuss it with `clearly_comment`. They take a `target`: a path (`~/Q1/Plan.md`), a key',
-        '  (`CLR-42`), an id or an exact title. The extension names the type (`.md` document, `.csv`',
-        '  sheet, `.board.json` board); a trailing slash means a project.',
-        '- Search before you write, and write decisions back so the next session inherits them.',
-        '- If a job is not covered by a listed tool, say so rather than guessing an action name.',
-        MCP_BLOCK_END,
+        'If this session has neither the `clearly_*` tools nor `beehaven`, stop and ask the person to connect',
+        'Clearly (clearly.sh/docs/mcp or clearly.sh/docs/cli). Do not skip the tracking.',
+        AGENTS_MD_END,
     ].join('\n');
 }

package/dist/build-channel.js

@@ -53,9 +53,9 @@ export const PUBLIC_BUILD = true;
  * ⚠ REWRITTEN IN `dist/` AT BUILD TIME, like `PUBLIC_BUILD`. `unstamped` is what a source checkout
  * carries and what `tsx`/`vitest` see, and it is honest: nothing has stamped them.
  */
-export const BUILD_SHA = '0fc3f190acdb';
+export const BUILD_SHA = 'f866489dd2f1';
 /** ISO-8601 minute precision, UTC. Rewritten in `dist/` by `scripts/stamp-build-channel.mjs`. */
-export const BUILD_TIME = '2026-10-27T20:29Z';
+export const BUILD_TIME = '2026-10-28T16:02Z';
 /**
  * The build identity as one short string, for `--version`.
  *

package/dist/cli.js

@@ -1340,7 +1340,7 @@ async function run() {
             state: { type: 'string' },
             goal: { type: 'string' },
             remove: { type: 'boolean', default: false },
-            // `agents-md`: the MCP block instead of the CLI one; print it instead of writing it (CAN2-66).
+            // `agents-md`: `--mcp` is accepted for older instructions (one block since AWO-401); `--print` prints it.
             mcp: { type: 'boolean', default: false },
             print: { type: 'boolean', default: false },
             /**

package/dist/commands/agents-md.js

@@ -8,17 +8,81 @@
  * is its own command the person (or their agent, asked first) runs, not a side effect of install.
  *
  * ⚠ THE MARKERS ARE THE UPDATE MECHANISM, as on every other surface (lib/connections/agentsMd.ts):
- * re-running replaces only what lies between our markers and leaves the rest byte for byte. The
- * CLI and MCP blocks have their own markers, so a repo used both ways keeps both.
+ * re-running replaces only what lies between our markers and leaves the rest byte for byte.
+ *
+ * ⚠ ONE TRACKED BLOCK FOR BOTH ROUTES (AWO-401). The block names the MCP tool and the CLI command
+ * for each step, so `--mcp` is kept only so older instructions still work; it writes the same block.
+ * Writing it removes the per-route blocks earlier versions wrote (`LEGACY_BLOCK_MARKERS`), so a repo
+ * that had both converges on one.
  *
  * ⚠ AGENTS.md IS THE FILE; CLAUDE.md POINTS AT IT with one `@AGENTS.md` line — one copy to keep
  * current. An existing CLAUDE.md gains the line only if it lacks it; nothing else in it is touched.
+ * The project's `.claude/settings.json` gains `CLAUDE_BASH_RULE` the same way (AWO-401).
  */
-import { existsSync, readFileSync, writeFileSync } from 'fs';
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'fs';
 import { join, resolve } from 'path';
 import { execFileSync } from 'child_process';
 import { color } from '../spinner.js';
-import { CLI_BLOCK_START, CLI_BLOCK_END, MCP_BLOCK_START, MCP_BLOCK_END, CLAUDE_MD_IMPORT, agentsMdCliBlock, agentsMdMcpBlock, } from '../agents-md-text.js';
+import { AGENTS_MD_START, AGENTS_MD_END, LEGACY_BLOCK_MARKERS, CLAUDE_MD_IMPORT, agentsMdBlock } from '../agents-md-text.js';
+/**
+ * The Claude Code permission that lets an agent run `beehaven` without a prompt per call (AWO-401).
+ * The tracked block makes several calls a task; a prompt on each one pushes people to turn tracking
+ * off. Written to the PROJECT's `.claude/settings.json` (committed with AGENTS.md, so it is the
+ * team's rule, not a change to anyone's user-wide settings). Claude Code matches each part of a
+ * chained command separately, so the rule never approves `beehaven … && something-else`.
+ */
+export const CLAUDE_BASH_RULE = 'Bash(beehaven:*)';
+/**
+ * Settings text with the rule added (or removed). `null` text means no file. A file that is not a
+ * JSON object is left alone (`skipped`) — never rewritten from a guess.
+ */
+export function editClaudeSettings(text, remove = false) {
+    if (text === null) {
+        if (remove)
+            return { next: null, change: 'absent' };
+        return { next: JSON.stringify({ permissions: { allow: [CLAUDE_BASH_RULE] } }, null, 2) + '\n', change: 'created' };
+    }
+    let data;
+    try {
+        data = JSON.parse(text);
+    }
+    catch {
+        return { next: text, change: 'skipped' };
+    }
+    if (!data || typeof data !== 'object' || Array.isArray(data))
+        return { next: text, change: 'skipped' };
+    const perms = data.permissions && typeof data.permissions === 'object' && !Array.isArray(data.permissions) ? data.permissions : null;
+    const allow = perms && Array.isArray(perms.allow) ? perms.allow : [];
+    if (remove) {
+        if (!allow.includes(CLAUDE_BASH_RULE))
+            return { next: text, change: 'absent' };
+        perms.allow = allow.filter((r) => r !== CLAUDE_BASH_RULE);
+        if (!perms.allow.length)
+            delete perms.allow;
+        if (!Object.keys(perms).length)
+            delete data.permissions;
+        return { next: Object.keys(data).length ? JSON.stringify(data, null, 2) + '\n' : null, change: 'removed' };
+    }
+    if (allow.includes(CLAUDE_BASH_RULE))
+        return { next: text, change: 'current' };
+    if (perms && perms.allow !== undefined && !Array.isArray(perms.allow))
+        return { next: text, change: 'skipped' };
+    data.permissions = { ...(perms ?? {}), allow: [...allow, CLAUDE_BASH_RULE] };
+    return { next: JSON.stringify(data, null, 2) + '\n', change: 'updated' };
+}
+/** Apply `editClaudeSettings` to `<root>/.claude/settings.json`. */
+function writeClaudeSettings(root, remove) {
+    const path = join(root, '.claude', 'settings.json');
+    const before = existsSync(path) ? readFileSync(path, 'utf8') : null;
+    const { next, change } = editClaudeSettings(before, remove);
+    if (next === null && before !== null)
+        rmSync(path);
+    else if (next !== null && next !== before) {
+        mkdirSync(join(root, '.claude'), { recursive: true });
+        writeFileSync(path, next);
+    }
+    return { path, change };
+}
 /** Our block replaced between its markers, or appended after one blank line. Keeps CRLF files CRLF. */
 export function spliceBlock(text, block, start, end) {
     const eol = text.includes('\r\n') ? '\r\n' : '\n';
@@ -57,22 +121,42 @@ export function projectRoot(dir) {
     }
 }
 /** Write (or remove) the block in `<root>/AGENTS.md` and make CLAUDE.md import it. */
+/** The text with every per-route block from before AWO-401 taken out. */
+export function removeLegacyBlocks(text) {
+    return LEGACY_BLOCK_MARKERS.reduce((t, [start, end]) => removeBlock(t, start, end), text);
+}
+/**
+ * The block written into `text`: in place of our current block, else in place of the first legacy
+ * block (so a migrated repo keeps its layout), else appended. Any other legacy block is removed.
+ */
+export function upsertAgentsMdBlock(text, block) {
+    if (text.includes(AGENTS_MD_START))
+        return spliceBlock(removeLegacyBlocks(text), block, AGENTS_MD_START, AGENTS_MD_END);
+    const legacy = LEGACY_BLOCK_MARKERS.find(([start, end]) => {
+        const i = text.indexOf(start);
+        return i >= 0 && text.indexOf(end, i) >= 0;
+    });
+    if (legacy)
+        return removeLegacyBlocks(spliceBlock(text, block, legacy[0], legacy[1]));
+    return spliceBlock(text, block, AGENTS_MD_START, AGENTS_MD_END);
+}
+/** `mcp` is accepted for older instructions and changes nothing: there is one block (AWO-401). */
 export function writeProjectAgentsMd(opts) {
     const root = projectRoot(resolve(opts.dir));
-    const [start, end] = opts.mcp ? [MCP_BLOCK_START, MCP_BLOCK_END] : [CLI_BLOCK_START, CLI_BLOCK_END];
     const agentsPath = join(root, 'AGENTS.md');
     const claudePath = join(root, 'CLAUDE.md');
     const files = [];
     const had = existsSync(agentsPath);
     const before = had ? readFileSync(agentsPath, 'utf8') : '';
     if (opts.remove) {
-        const next = removeBlock(before, start, end);
+        const next = removeLegacyBlocks(removeBlock(before, AGENTS_MD_START, AGENTS_MD_END));
         if (next !== before)
             writeFileSync(agentsPath, next);
         files.push({ path: agentsPath, change: next !== before ? 'removed' : 'absent' });
+        files.push(writeClaudeSettings(root, true));
         return { root, files };
     }
-    const next = spliceBlock(before, opts.mcp ? agentsMdMcpBlock() : agentsMdCliBlock(), start, end);
+    const next = upsertAgentsMdBlock(before, agentsMdBlock());
     if (next !== before)
         writeFileSync(agentsPath, next);
     files.push({ path: agentsPath, change: !had ? 'created' : next !== before ? 'updated' : 'current' });
@@ -89,11 +173,12 @@ export function writeProjectAgentsMd(opts) {
     else {
         files.push({ path: claudePath, change: 'current' });
     }
+    files.push(writeClaudeSettings(root, false));
     return { root, files };
 }
 export function cmdAgentsMd(dir, opts) {
     if (opts.print) {
-        process.stdout.write((opts.mcp ? agentsMdMcpBlock() : agentsMdCliBlock()) + '\n');
+        process.stdout.write(agentsMdBlock() + '\n');
         return 0;
     }
     let r;
@@ -106,10 +191,11 @@ export function cmdAgentsMd(dir, opts) {
     }
     console.log('');
     for (const f of r.files) {
-        const mark = f.change === 'current' || f.change === 'absent' ? color.dim('·') : color.green('✓');
-        console.log(`  ${mark} ${f.path}  ${color.dim(f.change)}`);
+        const mark = f.change === 'current' || f.change === 'absent' ? color.dim('·') : f.change === 'skipped' ? color.yellow('!') : color.green('✓');
+        const note = f.change === 'skipped' ? ` — not valid JSON, so left unchanged; add "${CLAUDE_BASH_RULE}" to permissions.allow yourself` : '';
+        console.log(`  ${mark} ${f.path}  ${color.dim(f.change)}${note}`);
     }
-    const changed = r.files.some((f) => f.change !== 'current' && f.change !== 'absent');
+    const changed = r.files.some((f) => f.change !== 'current' && f.change !== 'absent' && f.change !== 'skipped');
     if (changed && !opts.remove) {
         console.log(color.dim(`\n  Commit ${r.files.map((f) => f.path.slice(r.root.length + 1)).join(' and ')} so every agent that opens this project knows the workspace.`));
     }

package/dist/commands/help.js

@@ -414,23 +414,26 @@ const PAGES = {
         related: ['login', 'guide'],
     },
     'agents-md': {
-        synopsis: 'beehaven agents-md [dir] [--mcp] [--print] [--remove]',
+        synopsis: 'beehaven agents-md [dir] [--print] [--remove]',
         description: `Add the Clearly block to this project's AGENTS.md, so every agent that opens the
-    repository — a teammate's Codex or Claude Code, a cloud agent, CI — knows the workspace and how
-    to reach it. Writes at the git root (or the directory given), and makes CLAUDE.md import it with
-    one \`@AGENTS.md\` line. Needs no login.
-
-    The block sits between Clearly's markers: run it again to update the block, and everything
-    else in the file stays as it was. \`beehaven login\` already teaches the agents on THIS machine
-    (their global instruction files); this is the shared, committed copy for everyone else.`,
+    repository — a teammate's Codex or Claude Code, a cloud agent, CI — tracks its work in the
+    workspace: sign in, a ticket for every task, a handoff at the end. One block serves agents on
+    the CLI and over MCP. Writes at the git root (or the directory given), and makes CLAUDE.md
+    import it with one \`@AGENTS.md\` line, and lets Claude Code run \`beehaven\` without a prompt per
+    call (\`Bash(beehaven:*)\` in the project's .claude/settings.json). Needs no login.
+
+    The block sits between Clearly's markers: run it again to update it, and everything else in
+    the file stays as it was. Older per-route Clearly blocks are replaced. \`beehaven login\`
+    already points the agents on THIS machine at Clearly (their global instruction files); this is
+    the shared, committed copy for everyone who opens the repository.`,
         flags: [
-            { name: '--mcp', desc: 'Write the block for agents connected over MCP instead of the CLI' },
             { name: '--print', desc: 'Print the block and write nothing' },
             { name: '--remove', desc: 'Take the block out again' },
+            { name: '--mcp', desc: 'Accepted for older instructions; the block is the same for MCP and the CLI' },
         ],
         examples: [
-            { cmd: 'beehaven agents-md', note: 'AGENTS.md + CLAUDE.md at the repository root' },
-            { cmd: 'beehaven agents-md --mcp', note: 'for a team that connects over MCP' },
+            { cmd: 'beehaven agents-md', note: 'AGENTS.md, CLAUDE.md and .claude/settings.json at the repository root' },
+            { cmd: 'beehaven agents-md --print', note: 'see the block without writing it' },
         ],
         related: ['skills', 'login'],
     },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clearlysh/beehaven",
-  "version": "0.8.34",
+  "version": "0.8.35",
   "description": "Beehaven CLI — command your Clearly workspace, agents, and canvas from the terminal",
   "private": false,
   "type": "module",