ai-agentmanager 1.12.0 → 1.13.0

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## 1.13.0 (2026-11-01)
+
+- **Agents are built in an agent session.** **+ Build an agent** now starts an agent session that works in the new agent's folder (`~/.agentmanager/built/<name>/`) and goes straight to it. The session writes the analysis (`analysis.json`), `agent.yaml`, `instructions.md` and `tests.yaml`, and checks that the agent loads. You keep shaping the agent in that conversation, like any other session (terminal, resume, inbox).
+- The session's page has a panel for its agent: status, tests, **Run tests**, **Start**/**Stop**, its chat, **Details**. Failing tests go back to the session with **Ask this session to fix them**.
+- In the Built tab, each agent links to its session. The details dialog has a box that sends a change request to the session. Agents built before this get **Open a session for it**.
+- Test results and executables built before the agent's latest change are marked as out of date. Deleting a built agent closes its session; the conversation is kept.
+- **Fixes from building a real agent:**
+  - A permission prompt is now flagged when newer Claude Code blinks a ⏺ beside the pending tool call. The blinking used to keep the session looking busy, so the prompt never reached the Inbox. This affects every session, not just build sessions.
+  - agentkit agents can write files under a folder they're allowed: Claude Code ignores `Write(<path>)` allow rules, so each one now also gets its `Edit(<path>)` rule.
+  - The test judge sees the files each test run created or changed, not only the agent's reply, and the Tests list shows them.
+  - Build sessions read the agentkit reference without asking, and write the agent's files with their file tools.
+- The build dialog takes an optional name; otherwise the name comes from the task's first words. `POST /api/builder/:name/change` sends a change request to the session from scripts.
+
 ## 1.12.0 (2026-11-01)
 
 - **agentkit (phase 1): agents you build and run.** An agent is a folder with `agent.yaml` (goal, instructions, engine, MCP tools, allow/approve lists, triggers, loop, memory, interfaces); `agentkit run <agent>` runs it continuously. Each input is a run of plan → act → check (acting again on what's left, up to `maxSteps`) → reflect into memory, through an engine's CLI (Claude Code, Codex, Muse Code or an ACP agent), self-contained (only its own MCP servers; none of your personal Claude settings). Triggers: `every`, `cron`, `webhook`, `watch`. Interfaces: a chat page and HTTP API, A2A (agent card and `message/send` / `tasks/get`), ACP on stdio (`agentkit acp`), and an MCP tool (`agentkit mcp`, one tool `ask_<name>`). `agentkit init`, `check`, `run --once`. See [docs/agentkit.md](docs/agentkit.md).

package/docs/agentkit.md

@@ -27,7 +27,8 @@ tools:                              # MCP servers the engine gets
     command: npx
     args: [-y, "@acme/jira-mcp"]
     env: { JIRA_TOKEN: "${JIRA_TOKEN}" }  # "${VAR}" (quoted) comes from the environment, never stored
-allow: [Read, Grep, "mcp__jira__*"] # tools it may use without asking (engine names)
+allow: [Read, Grep, "mcp__jira__*"] # tools it may use without asking (engine names);
+                                    # "Edit(./out/**)" lets it write files under ./out only
 approve: ["mcp__jira__transition"]  # tools that need a person's yes (asked in chat / Inbox)
 approveTimeout: 30m                 # no answer by then counts as no
 report:                             # report to AI Agent Manager (or set AGENTKIT_REPORT_*)
@@ -55,6 +56,19 @@ interfaces:
   mcp: true                         # `<agent> mcp` exposes it as an MCP tool
 ```
 
+## Building one in AI Agent Manager
+
+**Built → + Build an agent** takes a task or workflow (attachments welcome), the engine it runs on and an optional name. It starts an **agent session** whose folder is the new agent (`~/.agentmanager/built/<name>/`), and opens that session. The session writes the agent and checks that it loads (`agentkit check`):
+
+- `analysis.json`: the problem, inputs, outputs, risks and the MCP tools it chose
+- `agent.yaml`
+- `instructions.md`
+- `tests.yaml`: 3 to 8 `{input, expect}` cases
+
+It asks you what only you know: accounts, labels, teams. You keep developing the agent in that conversation.
+
+The session's page shows a panel for its agent: status and test results, with **Run tests** (each test runs through the real runtime and is judged against `expect`), **Start**/**Stop** (runs it continuously on this computer, with its chat page and API) and **Details**. Failing tests can go straight back to the session. The Built tab lists every built agent with a link to its session. Its details dialog sends change requests to the session and has the spec, executables and downloads. Results and executables from before the latest change are marked out of date.
+
 ## A run
 
 1. **Input** arrives: a trigger fires (with its payload), someone chats, an A2A task or an MCP

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-agentmanager",
-  "version": "1.12.0",
+  "version": "1.13.0",
   "description": "Run background coding agents (Claude Code, Codex) per intent, and keep track of them from a web UI, your phone or the CLI",
   "keywords": [
     "claude",

package/public/app.js

@@ -127,7 +127,14 @@ $('#new-playbook').onclick = () => {
 };
 $('#triggers-open').onclick = () => triggersUi.open();
 let builtReports = []; // agents built with agentkit that report here (runs, approvals)
-const builtUi = initBuilt({ api, esc, toast, $, isOpen: () => sideTab === 'built', setCount: (n) => ($('#built-count').textContent = n), reports: () => builtReports });
+const builtUi = initBuilt({
+  api, esc, toast, $,
+  isOpen: () => sideTab === 'built',
+  setCount: (n) => ($('#built-count').textContent = n),
+  reports: () => builtReports,
+  openSession: (id) => (showTab('agents'), select(id)),
+  onPanel: () => agents.get(selectedId)?.builds && renderDetail(),
+});
 const landUi = initLand({ api, esc, toast, agents, $, scoreBadge, select: (id) => (showTab('agents'), select(id)), openReview: (id) => reviewUi.open(id), isOpen: () => sideTab === 'land' });
 
 function statusOf(a) {
@@ -713,7 +720,7 @@ function agentItem(a) {
   const idle = !isActive(a);
   return `<li data-id="${a.id}" ${a.kind === 'general' || a.kind === 'assistant' ? '' : 'draggable="true" '}class="agent pr${a.priority ?? 2} ${a.id === selectedId ? 'selected' : ''} ${idle ? 'idle' : ''}">
     <div class="line1">${prioChip(a.priority ?? 2)}${a.results?.outcome === 'blocked' ? '<span class="outcome-mark" title="Blocked">⛔</span>' : a.results?.outcome === 'done' ? '<span class="outcome-mark" title="Done">✅</span>' : ''}<span class="name">${esc(a.name)}</span>${flags(a)}<span class="pill ${st}">${pillText(st)}</span></div>
-    <div class="intent" title="${esc(describeTitle(a) ?? '')}">${a.kind === 'general' ? '<span class="tag">general</span> ' : a.kind === 'assistant' ? '<span class="tag assistant">assistant</span> ' : a.startedBy ? '<span class="tag assistant" title="Started by the assistant">🤖 by assistant</span> ' : a.trigger ? `<span class="tag assistant" title="Started from ${a.trigger.source === 'github' ? 'a labeled GitHub issue' : 'the webhook'}${a.trigger.url ? `: ${esc(a.trigger.url)}` : ''}">⚡ ${a.trigger.source === 'github' ? 'GitHub' : 'webhook'}</span> ` : a.playbook ? `<span class="tag assistant" title="Started by the playbook ${esc(a.playbook.name)}">▶ ${esc(a.playbook.name)}</span> ` : ''}${a.engine && a.engine !== 'claude' ? `<span class="tag engine">${esc(ENGINE_LABEL[a.engine] ?? a.engine)}</span> ` : ''}${a.isolation === 'container' ? '<span class="tag engine" title="Runs in its own Docker container: it sees only its own folder">📦 container</span> ' : ''}${esc(describe(a) || (a.kind === 'assistant' ? 'Finds new work and starts agents for it' : 'General session'))}</div>
+    <div class="intent" title="${esc(describeTitle(a) ?? '')}">${a.builds ? `<span class="tag assistant" title="Develops the agent ${esc(a.builds.name)} (Built tab)">⚙ builds agent</span> ` : ''}${a.kind === 'general' ? '<span class="tag">general</span> ' : a.kind === 'assistant' ? '<span class="tag assistant">assistant</span> ' : a.startedBy ? '<span class="tag assistant" title="Started by the assistant">🤖 by assistant</span> ' : a.trigger ? `<span class="tag assistant" title="Started from ${a.trigger.source === 'github' ? 'a labeled GitHub issue' : 'the webhook'}${a.trigger.url ? `: ${esc(a.trigger.url)}` : ''}">⚡ ${a.trigger.source === 'github' ? 'GitHub' : 'webhook'}</span> ` : a.playbook ? `<span class="tag assistant" title="Started by the playbook ${esc(a.playbook.name)}">▶ ${esc(a.playbook.name)}</span> ` : ''}${a.engine && a.engine !== 'claude' ? `<span class="tag engine">${esc(ENGINE_LABEL[a.engine] ?? a.engine)}</span> ` : ''}${a.isolation === 'container' ? '<span class="tag engine" title="Runs in its own Docker container: it sees only its own folder">📦 container</span> ' : ''}${esc(describe(a) || (a.kind === 'assistant' ? 'Finds new work and starts agents for it' : 'General session'))}</div>
     ${a.status === 'preparing' && a.progress ? `<div class="progress-line">${esc(progressText(a.progress))}</div>` : ''}
     <div class="meta">
       <span class="mono">${a.id}</span>
@@ -1743,6 +1750,7 @@ function renderDetail() {
     ${a.runtime.attention ? `<div class="error-box">${esc(a.runtime.attention)}: the agent is waiting for an answer. Open its terminal to respond.</div>` : ''}
     ${raceBanner(a)}
     ${teamBanner(a)}
+    ${a.builds ? builtUi.panel(a) : ''}
     ${a.forkOf ? `<div class="bl-banner">⑂ Forked from <a href="#${a.forkOf.agentId}" data-goto="${a.forkOf.agentId}">${esc(a.forkOf.name)}</a>${a.forkOf.checkpoint ? ` at checkpoint ${a.forkOf.checkpoint}` : ''} ${ago(a.forkOf.at)}</div>` : ''}
     ${(() => {
       const items = needsFor(a, { both: true });
@@ -3641,6 +3649,7 @@ function handleEvent(msg) {
     agents.set(msg.agent.id, msg.agent);
     watchDocs(msg.agent);
     agentChanged(msg.agent);
+    if (msg.agent.builds) builtUi.sessionChanged(msg.agent);
   } else if (msg.t === 'removed') {
     agents.delete(msg.id);
     if (selectedId === msg.id) select(null);

package/public/built.js

@@ -1,15 +1,22 @@
-// The Built tab: agents made with the builder (agentkit agents, docs/agentkit.md). Build one from
-// a task; review its analysis, spec and tests; test it; run it here; open its chat; download it.
+// The Built tab: agents made with the builder (agentkit agents, docs/agentkit.md). Each one is
+// developed in an agent session working in its folder: building one starts that session, and the
+// person keeps shaping the agent there. Here (and in a panel on that session) they review its
+// analysis, spec and tests, test it, run it here, open its chat, package and download it.
 import { attachBox } from '/attach.js';
 
-const STATUS = { designed: 'designed', 'needs-fixing': 'needs fixing', testing: 'testing…', tested: 'tests pass', failing: 'tests fail', running: 'running' };
+const STATUS = { designing: 'designing…', designed: 'designed', 'needs-fixing': 'needs fixing', testing: 'testing…', tested: 'tests pass', failing: 'tests fail', running: 'running' };
 
 const ago = (iso) => {
   const s = Math.max(0, (Date.now() - Date.parse(iso)) / 1000);
   return s < 60 ? 'just now' : s < 3600 ? `${Math.round(s / 60)} min ago` : s < 86400 ? `${Math.round(s / 3600)} h ago` : `${Math.round(s / 86400)} d ago`;
 };
 
-export function initBuilt({ api, esc, toast, $, isOpen, setCount, reports = () => [] }) {
+const sessionText = (s) => (!s ? 'no session' : s.attention ? 'session waiting for you' : s.busy ? 'session working' : s.running ? 'session idle' : 'session closed');
+const tagClass = (b) => (b.status === 'tested' ? 'open' : b.status === 'failing' || b.status === 'needs-fixing' ? 'fail' : '');
+const later = (a, b) => Boolean(a && b && Date.parse(a) > Date.parse(b) + 1000);
+
+/** `openSession(id)`: show an agent session (the agents view). `onPanel()`: a session's panel has new data. */
+export function initBuilt({ api, esc, toast, $, isOpen, setCount, reports = () => [], openSession = () => {}, onPanel = () => {} }) {
   const view = $('#built-view');
   const dlg = $('#built-dialog');
   const body = $('#built-body');
@@ -28,9 +35,9 @@ export function initBuilt({ api, esc, toast, $, isOpen, setCount, reports = () =
   }
 
   function render() {
-    view.innerHTML = `<div class="built-head"><button class="small primary" data-bt="new">+ Build an agent</button><span class="hint">An agent for a task or workflow: it plans, acts, checks itself and keeps working in the background.</span></div>
-      ${list.length ? `<ul class="built-list">${list.map((b) => `<li data-bt-open="${esc(b.name)}"><div class="line1"><b>${esc(b.title ?? b.name)}</b>${b.running ? ' <span class="dot-run" title="Running">●</span>' : ''}<span class="spacer"></span><span class="tag ${b.status === 'tested' ? 'open' : b.status === 'failing' || b.status === 'needs-fixing' ? 'fail' : ''}">${esc(b.pending ?? STATUS[b.status] ?? b.status)}</span></div>
-        <div class="hint">${esc(b.name)} · ${esc(b.engine ?? '')}${b.results?.total ? ` · tests ${b.results.passed}/${b.results.total}` : ''}${b.triggers.length ? ` · ${esc(b.triggers.join(', '))}` : ''}</div></li>`).join('')}</ul>` : '<p class="hint built-empty">No agents built yet.</p>'}
+    view.innerHTML = `<div class="built-head"><button class="small primary" data-bt="new">+ Build an agent</button><span class="hint">An agent for a task or workflow: it plans, acts, checks itself and keeps working in the background. Each is developed in its own agent session.</span></div>
+      ${list.length ? `<ul class="built-list">${list.map((b) => `<li data-bt-open="${esc(b.name)}"><div class="line1"><b>${esc(b.title ?? b.name)}</b>${b.running ? ' <span class="dot-run" title="Running">●</span>' : ''}<span class="spacer"></span>${b.session ? `<a href="#${esc(b.session.id)}" class="button small ghost" data-bt-session="${esc(b.session.id)}" title="Its session: where you shape it">Session${b.session.busy ? ' ●' : ''}</a>` : ''}<span class="tag ${tagClass(b)}">${esc(b.pending ?? STATUS[b.status] ?? b.status)}</span></div>
+        <div class="hint">${esc(b.name)} · ${esc(b.engine ?? '')} · ${sessionText(b.session)}${b.results?.total ? ` · tests ${b.results.passed}/${b.results.total}` : ''}${b.triggers.length ? ` · ${esc(b.triggers.join(', '))}` : ''}</div></li>`).join('')}</ul>` : '<p class="hint built-empty">No agents built yet.</p>'}
       ${reporting()}`;
   }
 
@@ -85,20 +92,23 @@ export function initBuilt({ api, esc, toast, $, isOpen, setCount, reports = () =
     if (files.pending()) return toast('Still uploading the attached files');
     const btn = f.querySelector('button[type=submit]');
     btn.disabled = true;
-    btn.textContent = 'Designing… (about a minute)';
+    btn.textContent = 'Starting its session…';
     try {
-      const b = await api('POST', '/builder', { task: f.task.value, engine: f.engine.value, attachments: files.paths().length ? files.paths() : undefined });
+      const b = await api('POST', '/builder', { task: f.task.value, engine: f.engine.value, name: f.name.value.trim() || undefined, attachments: files.paths().length ? files.paths() : undefined });
       buildDlg.close();
       f.reset();
       files.clear();
+      cache.set(b.name, b);
       await load();
-      show(b);
+      // Building happens in its session: go there.
+      if (b.session) openSession(b.session.id);
+      else show(b);
     } catch (err) {
       $('#build-error').textContent = err.message;
       $('#build-error').hidden = false;
     } finally {
       btn.disabled = false;
-      btn.textContent = 'Design the agent';
+      btn.textContent = 'Start building';
     }
   });
   $('#build-cancel').onclick = () => buildDlg.close();
@@ -110,28 +120,32 @@ export function initBuilt({ api, esc, toast, $, isOpen, setCount, reports = () =
     const a = b.analysis ?? {};
     const li = (xs) => (xs?.length ? `<ul>${xs.map((x) => `<li>${esc(x)}</li>`).join('')}</ul>` : '<p class="hint">—</p>');
     const r = b.results;
+    const failed = (r?.list ?? []).filter((t) => t.pass === false);
     body.innerHTML = `
+      ${sessionBlock(b)}
       <div class="built-actions">
-        <span class="tag ${b.status === 'tested' ? 'open' : b.status === 'failing' || b.status === 'needs-fixing' ? 'fail' : ''}">${esc(b.pending ?? STATUS[b.status] ?? b.status)}</span>
+        <span class="tag ${tagClass(b)}">${esc(b.pending ?? STATUS[b.status] ?? b.status)}</span>
         ${b.running ? `<span class="hint">running since ${new Date(b.running.since).toLocaleTimeString()}</span>${b.running.url ? ` <a href="${esc(b.running.url)}" target="_blank" rel="noopener">Open its chat ↗</a>` : ''}` : ''}
         <span class="spacer"></span>
-        <button class="small" data-bt="test" ${b.pending ? 'disabled' : ''} title="Run each test through the real engine and judge the results">${b.pending === 'testing' ? 'Testing…' : 'Run tests'}</button>
-        <button class="small ${b.running ? '' : 'primary'}" data-bt="${b.running ? 'stop' : 'start'}" ${b.specError ? 'disabled' : ''} title="${b.running ? 'Stop it' : 'Run it continuously on this computer: its triggers, chat page and API'}">${b.running ? 'Stop' : 'Start'}</button>
+        <button class="small" data-bt="test" ${b.pending || b.specError || b.status === 'designing' ? 'disabled' : ''} title="Run each test through the real engine and judge the results">${b.pending === 'testing' ? 'Testing…' : 'Run tests'}</button>
+        <button class="small ${b.running ? '' : 'primary'}" data-bt="${b.running ? 'stop' : 'start'}" ${b.specError || b.status === 'designing' ? 'disabled' : ''} title="${b.running ? 'Stop it' : 'Run it continuously on this computer: its triggers, chat page and API'}">${b.running ? 'Stop' : 'Start'}</button>
         <a class="button small ghost" href="/api/builder/${esc(b.name)}/download" title="Its folder (agent.yaml, instructions, tests) to run anywhere with agentkit">Download folder</a>
         <button class="small ghost" data-bt="delete">Delete</button>
       </div>
       <div class="built-exe"><b>Single executable</b> <span class="hint">one file that runs this agent anywhere, no Node or agentkit needed (its engine's CLI must be installed and signed in)</span>
         <div class="built-exe-row"><select id="built-platform">${(b.platforms ?? []).map((p) => `<option value="${esc(p)}" ${p === b.host ? 'selected' : ''}>${esc(p)}${p === b.host ? ' (this computer)' : ''}</option>`).join('')}</select>
-        <button class="small" data-bt="package" ${b.pending || b.specError ? 'disabled' : ''}>${b.pending?.startsWith('packaging') ? 'Building… (a minute or two)' : 'Build executable'}</button>
-        ${Object.entries(b.executables ?? {}).map(([p, x]) => `<a class="button small ghost" href="/api/builder/${esc(b.name)}/executable/${esc(p)}" title="Built ${esc(new Date(x.at).toLocaleString())}">⬇ ${esc(p)} · ${Math.round(x.size / 1e6)} MB</a>`).join('')}</div>
+        <button class="small" data-bt="package" ${b.pending || b.specError || b.status === 'designing' ? 'disabled' : ''}>${b.pending?.startsWith('packaging') ? 'Building… (a minute or two)' : 'Build executable'}</button>
+        ${Object.entries(b.executables ?? {}).map(([p, x]) => `<a class="button small ghost" href="/api/builder/${esc(b.name)}/executable/${esc(p)}" title="Built ${esc(new Date(x.at).toLocaleString())}${later(b.changedAt, x.at) ? ', before its latest change: build it again' : ''}">⬇ ${esc(p)} · ${Math.round(x.size / 1e6)} MB${later(b.changedAt, x.at) ? ' (older)' : ''}</a>`).join('')}</div>
         ${b.packageError ? `<p class="error">${esc(b.packageError)}</p>` : ''}</div>
       ${b.specError ? `<p class="error">${esc(b.specError)}</p>` : ''}
       ${b.missingEnv.length ? `<p class="hint warn">Set these in the environment before running it: ${esc(b.missingEnv.join(', '))}</p>` : ''}
-      <details open><summary><b>Analysis</b></summary><p>${esc(a.problem ?? '')}</p><div class="row three"><div><b>Inputs</b>${li(a.inputs)}</div><div><b>Outputs</b>${li(a.outputs)}</div><div><b>Risks</b>${li(a.risks)}</div></div>
+      <details open><summary><b>Analysis</b></summary>${b.status === 'designing' && !a.problem ? '<p class="hint">Its session is working it out; this fills in as it writes the files.</p>' : ''}<p>${esc(a.problem ?? '')}</p><div class="row three"><div><b>Inputs</b>${li(a.inputs)}</div><div><b>Outputs</b>${li(a.outputs)}</div><div><b>Risks</b>${li(a.risks)}</div></div>
         ${b.tools?.length ? `<p><b>Tools</b></p><ul>${b.tools.map((t) => `<li><code>${esc(t.name)}</code> ${esc(t.why)}</li>`).join('')}</ul>` : ''}</details>
       <details ${r ? 'open' : ''}><summary><b>Tests</b> ${r?.total ? `<span class="hint">${r.passed}/${r.total} pass · ${new Date(r.at).toLocaleString()}</span>` : '<span class="hint">not run yet</span>'}</summary>
         ${r?.error ? `<p class="error">${esc(r.error)}</p>` : ''}
-        <ol class="built-tests">${(r?.list?.length ? r.list : b.tests ?? []).map((t) => `<li class="${t.pass === true ? 'pass' : t.pass === false ? 'fail' : ''}"><div><b>${t.pass === true ? '✓' : t.pass === false ? '✗' : '·'}</b> ${esc(t.input)}</div><div class="hint">Expect: ${esc(t.expect)}</div>${t.why ? `<div class="hint">${esc(t.why)}</div>` : ''}${t.result ? `<details><summary class="hint">Result</summary><pre>${esc(t.result)}</pre></details>` : ''}</li>`).join('')}</ol></details>
+        ${r?.at && later(b.changedAt, r.at) ? '<p class="hint warn">The agent changed after these results; run the tests again.</p>' : ''}
+        ${failed.length && b.session ? `<button class="small" data-bt="fix">Ask its session to fix the ${failed.length} failing test${failed.length > 1 ? 's' : ''}</button>` : ''}
+        <ol class="built-tests">${(r?.list?.length ? r.list : b.tests ?? []).map((t) => `<li class="${t.pass === true ? 'pass' : t.pass === false ? 'fail' : ''}"><div><b>${t.pass === true ? '✓' : t.pass === false ? '✗' : '·'}</b> ${esc(t.input)}</div><div class="hint">Expect: ${esc(t.expect)}</div>${t.why ? `<div class="hint">${esc(t.why)}</div>` : ''}${t.files?.length ? `<div class="hint">Wrote: ${t.files.map((f) => `<code>${esc(f)}</code>`).join(', ')}</div>` : ''}${t.result ? `<details><summary class="hint">Result</summary><pre>${esc(t.result)}</pre></details>` : ''}</li>`).join('')}</ol></details>
       <details><summary><b>agent.yaml</b> and instructions</summary>
         <textarea id="built-yaml" class="code-area" rows="16" spellcheck="false">${esc(b.yaml)}</textarea>
         <textarea id="built-instr" class="code-area" rows="10" spellcheck="false">${esc(b.instructionsText)}</textarea>
@@ -140,15 +154,31 @@ export function initBuilt({ api, esc, toast, $, isOpen, setCount, reports = () =
       <p class="hint">Task: ${esc(b.task ?? '')}</p>`;
     if (!dlg.open) dlg.showModal();
     clearInterval(poll);
-    if (b.pending) poll = setInterval(refresh, 3000);
+    if (b.pending || b.status === 'designing') poll = setInterval(refresh, 3000);
+  }
+
+  // Where the agent is developed: its session, and a box to ask it for a change.
+  function sessionBlock(b) {
+    if (!b.session)
+      return `<div class="built-session"><b>No session</b> <span class="hint">Open an agent session in its folder to keep shaping it with you.</span><span class="spacer"></span><button class="small primary" data-bt="session-new">Open a session for it</button></div>`;
+    return `<div class="built-session"><div class="line1"><b>Developed in its session</b> <span class="hint">${sessionText(b.session)}</span><span class="spacer"></span><a href="#${esc(b.session.id)}" class="button small primary" data-bt-session="${esc(b.session.id)}">Open session</a></div>
+      <div class="built-change"><textarea id="built-change" rows="2" placeholder="Ask its session for a change: “also post a summary to #support every evening”, “never reassign tickets”…"></textarea><button class="small" data-bt="change">Send</button></div></div>`;
+  }
+
+  function failuresText(b) {
+    const failed = (b.results?.list ?? []).filter((t) => t.pass === false);
+    return `These tests failed. Change the agent so they pass (or fix a test if its expectation is wrong), check it, and tell me what you changed.\n\n${failed.map((t, i) => `${i + 1}. Input: ${t.input}\n   Expected: ${t.expect}\n   Judge: ${t.why}\n   Result: ${String(t.result ?? '').slice(0, 600)}`).join('\n\n')}`;
   }
 
   async function refresh() {
     if (!open || !dlg.open) return clearInterval(poll);
     try {
       const b = await api('GET', `/builder/${open.name}`);
-      if (b.pending !== open.pending || b.updatedAt !== open.updatedAt) show(b);
-      if (!b.pending) clearInterval(poll), load();
+      cache.set(b.name, b);
+      onPanel();
+      const typing = document.activeElement?.closest?.('#built-body textarea');
+      if (!typing && JSON.stringify(b) !== JSON.stringify(open)) show(b);
+      if (!b.pending && b.status !== 'designing') clearInterval(poll), load();
     } catch {}
   }
 
@@ -161,6 +191,16 @@ export function initBuilt({ api, esc, toast, $, isOpen, setCount, reports = () =
         show(await api('POST', `/builder/${name}/start`));
         setTimeout(refresh, 1500);
       } else if (what === 'stop') show(await api('POST', `/builder/${name}/stop`));
+      else if (what === 'change' || what === 'fix') {
+        const text = what === 'fix' ? failuresText(open) : $('#built-change').value.trim();
+        if (!text) return toast('Say what to change');
+        show(await api('POST', `/builder/${name}/change`, { text }));
+        toast('Sent to its session');
+      } else if (what === 'session-new') {
+        const b = await api('POST', `/builder/${name}/change`, {});
+        dlg.close();
+        if (b.session) openSession(b.session.id);
+      }
       else if (what === 'save') {
         show(await api('PUT', `/builder/${name}`, { yaml: $('#built-yaml').value, instructions: $('#built-instr').value }));
         toast('Saved');
@@ -193,15 +233,100 @@ export function initBuilt({ api, esc, toast, $, isOpen, setCount, reports = () =
       }
       return;
     }
+    const ses = e.target.closest('[data-bt-session]');
+    if (ses) return e.preventDefault(), openSession(ses.dataset.btSession);
     const li = e.target.closest('[data-bt-open]');
     if (li) show(await api('GET', `/builder/${li.dataset.btOpen}`));
   });
   body.addEventListener('click', (e) => {
+    const ses = e.target.closest('[data-bt-session]');
+    if (ses) return e.preventDefault(), dlg.close(), openSession(ses.dataset.btSession);
     const b = e.target.closest('[data-bt]');
     if (b) act(b.dataset.bt);
   });
   $('#built-close').onclick = () => (clearInterval(poll), dlg.close());
 
+  // ------------------------------------------------------------ the panel on its session
+  const cache = new Map(); // name -> its latest view (or { missing: true })
+  const fetching = new Set();
+  async function fetchOne(name) {
+    if (fetching.has(name)) return;
+    fetching.add(name);
+    try {
+      cache.set(name, await api('GET', `/builder/${encodeURIComponent(name)}`));
+    } catch (err) {
+      cache.set(name, /No built agent|Unknown agent/.test(err.message) ? { missing: true, name } : { error: err.message, name });
+    } finally {
+      fetching.delete(name);
+      onPanel();
+    }
+  }
+
+  /** The panel shown on a session that builds an agent (agent `a`, with a.builds). */
+  function panel(a) {
+    const name = a.builds.name;
+    const b = cache.get(name);
+    if (!b) {
+      fetchOne(name);
+      return `<div class="built-panel"><b>⚙ Builds the agent ${esc(name)}</b> <span class="hint">loading…</span></div>`;
+    }
+    if (b.error) return `<div class="built-panel"><b>⚙ Builds the agent ${esc(name)}</b> <span class="hint">· ${esc(b.error)}</span></div>`;
+    if (b.missing) return `<div class="built-panel"><b>⚙ Built the agent ${esc(name)}</b> <span class="hint">· deleted from the Built tab</span></div>`;
+    const r = b.results;
+    const failed = (r?.list ?? []).filter((t) => t.pass === false);
+    const stale = r?.at && later(b.changedAt, r.at);
+    return `<div class="built-panel" data-bp-name="${esc(name)}">
+      <div class="line1"><b>⚙ ${esc(b.title ?? name)}</b> <span class="tag ${tagClass(b)}">${esc(b.pending ?? STATUS[b.status] ?? b.status)}</span>
+        <span class="hint">${esc(b.engine ?? '')}${b.triggers.length ? ` · ${esc(b.triggers.join(', '))}` : ''}${r?.total ? ` · tests ${r.passed}/${r.total}${stale ? ' (before the latest change)' : ''}` : b.tests.length ? ` · ${b.tests.length} tests, not run` : ''}${b.running ? ' · running here' : ''}</span>
+        <span class="spacer"></span>
+        <button class="small" data-bp="test" ${b.pending || b.specError || b.status === 'designing' ? 'disabled' : ''} title="Run each test through the real engine and judge the results">${b.pending === 'testing' ? 'Testing…' : 'Run tests'}</button>
+        <button class="small" data-bp="${b.running ? 'stop' : 'start'}" ${b.specError || b.status === 'designing' ? 'disabled' : ''} title="${b.running ? 'Stop it' : 'Run it continuously on this computer: its triggers, chat page and API'}">${b.running ? 'Stop' : 'Start'}</button>
+        ${b.running?.url ? `<a class="button small ghost" href="${esc(b.running.url)}" target="_blank" rel="noopener">Chat ↗</a>` : ''}
+        <button class="small ghost" data-bp="open" title="Analysis, spec, tests, executables, downloads">Details</button></div>
+      ${b.specError ? `<p class="error">${esc(b.specError)}</p>` : ''}
+      ${b.missingEnv.length ? `<p class="hint warn">Needs in the environment before it runs: ${esc(b.missingEnv.join(', '))}</p>` : ''}
+      ${b.description ? `<div class="hint">${esc(b.description)}</div>` : ''}
+      ${failed.length && !stale ? `<div class="hint">Failing: ${failed.map((t) => esc(t.input.slice(0, 60))).join(' · ')} <button class="small" data-bp="fix">Ask this session to fix them</button></div>` : ''}
+    </div>`;
+  }
+
+  document.addEventListener('click', async (e) => {
+    const el = e.target.closest('[data-bp]');
+    if (!el) return;
+    const name = el.closest('[data-bp-name]').dataset.bpName;
+    try {
+      if (el.dataset.bp === 'open') return show(await api('GET', `/builder/${name}`));
+      if (el.dataset.bp === 'fix') {
+        await api('POST', `/builder/${name}/change`, { text: failuresText(cache.get(name)) });
+        return toast('Sent to this session');
+      }
+      el.disabled = true;
+      cache.set(name, await api('POST', `/builder/${name}/${el.dataset.bp}`));
+      onPanel();
+      // Tests and starting finish in the background; follow them.
+      const follow = setInterval(async () => {
+        await fetchOne(name);
+        const b = cache.get(name);
+        if (!b || b.missing || (!b.pending && (el.dataset.bp !== 'start' || b.running?.url || !b.running))) clearInterval(follow), load();
+      }, 2000);
+    } catch (err) {
+      toast(`Error: ${err.message}`, 6000);
+    }
+  });
+
+  // Its session changed (it edits the files as it goes): fetch the agent again, a moment later.
+  const timers = new Map();
+  function sessionChanged(a) {
+    const name = a.builds?.name;
+    if (!name) return;
+    clearTimeout(timers.get(name));
+    timers.set(name, setTimeout(() => {
+      fetchOne(name);
+      if (open?.name === name && dlg.open) refresh();
+      if (isOpen()) load();
+    }, 1000));
+  }
+
   load();
-  return { load, render };
+  return { load, render, panel, sessionChanged, openAgent: async (name) => show(await api('GET', `/builder/${name}`)) };
 }

package/public/index.html

@@ -382,14 +382,15 @@
     <dialog id="build-dialog">
       <form id="build-form" method="dialog">
         <h2>Build an agent</h2>
-        <p class="hint">Describe the task or workflow it takes over: what comes in, what it should do, what it must never do. It's designed for you to review (analysis, spec, test cases) before it runs.</p>
+        <p class="hint">Describe the task or workflow it takes over: what comes in, what it should do, what it must never do. An agent session works it out with you in the agent's own folder (analysis, spec, instructions, test cases); you keep shaping it there, then test, run and package it.</p>
         <label>Task or workflow
           <textarea name="task" rows="8" required placeholder="Every morning, look at new support tickets in Jira, label each by product area, route it to the right team, and draft a first reply for a person to send. Never close or reply to tickets on its own."></textarea>
         </label>
         <div id="build-attach"></div>
-        <label>Engine <select name="engine"><option value="claude">Claude Code</option></select></label>
+        <div class="row"><label>Engine it runs on <select name="engine"><option value="claude">Claude Code</option></select></label>
+        <label>Name <input name="name" placeholder="from the task" pattern="[a-z][a-z0-9-]{1,40}" title="lowercase letters, digits and dashes"></label></div>
         <p id="build-error" class="error" hidden></p>
-        <div class="dialog-actions"><button type="button" id="build-cancel" class="ghost">Cancel</button><button type="submit" class="primary">Design the agent</button></div>
+        <div class="dialog-actions"><button type="button" id="build-cancel" class="ghost">Cancel</button><button type="submit" class="primary">Start building</button></div>
       </form>
     </dialog>
 

package/public/style.css

@@ -968,6 +968,12 @@ body.remote .settings-links .local-only { display: none; }
 .built-body details > summary { cursor: pointer; padding: 4px 0; }
 .built-actions { display: flex; align-items: center; gap: 8px; flex-wrap: wrap; }
 .built-exe { margin: 10px 0; padding: 8px 10px; border: 1px solid var(--border); border-radius: 8px; }
+.built-session, .built-panel { margin: 0 0 10px; padding: 8px 10px; border: 1px solid var(--border); border-radius: 8px; background: var(--panel, transparent); }
+.built-session .line1, .built-panel .line1 { display: flex; align-items: center; gap: 6px; flex-wrap: wrap; }
+.built-panel { margin: 10px 0; }
+.built-panel p { margin: 6px 0 0; }
+.built-change { display: flex; gap: 6px; margin-top: 6px; align-items: flex-end; }
+.built-change textarea { flex: 1; min-width: 0; }
 .built-exe-row { display: flex; align-items: center; gap: 8px; flex-wrap: wrap; margin-top: 6px; }
 .built-tests li { margin-bottom: 8px; } .built-tests li.pass b { color: var(--green); } .built-tests li.fail b { color: var(--red); }
 .built-tests pre, .built-runs div { white-space: pre-wrap; font-size: 12.5px; }

package/src/agentkit/engines.js

@@ -58,6 +58,19 @@ export function approverServer({ url, token }) {
   return { command: process.execPath, args: isSea() ? ['approver'] : [AGENTKIT_BIN, 'approver'], env: { AGENTKIT_APPROVAL_URL: url, AGENTKIT_APPROVAL_TOKEN: token } };
 }
 
+/**
+ * Claude Code scopes file writes with Edit(<path>) rules (they cover Write too); a Write(<path>)
+ * rule is ignored. Each Write(<path>) also gets its Edit(<path>), so writing there is allowed.
+ */
+export function claudeRules(allow) {
+  const out = [...allow];
+  for (const p of allow) {
+    const m = /^Write\((.+)\)$/.exec(p);
+    if (m && !out.includes(`Edit(${m[1]})`)) out.push(`Edit(${m[1]})`);
+  }
+  return out;
+}
+
 /**
  * One turn. `session`: the engine session to continue (null starts one); returns
  * { text, session, costUsd }. `system` goes in as an extra system prompt where the engine has one,
@@ -77,7 +90,7 @@ export async function turn(agent, { prompt, system = '', session = null, mcpFile
     args.push('--setting-sources', 'project', '--strict-mcp-config');
     if (mcpFile) args.push('--mcp-config', mcpFile);
     // The approve list wins: an allow pattern that also covers an approval tool goes to the approver.
-    const allow = approver ? allowedOutright(agent) : agent.allow;
+    const allow = claudeRules(approver ? allowedOutright(agent) : agent.allow);
     if (allow.length) args.push('--allowedTools', ...allow);
     // With an approver, Claude asks it before anything not allowed outright (it says no to tools
     // off the approve list); without one, approval tools are simply not available.

package/src/builder.js

@@ -1,6 +1,7 @@
-// The agent builder: a task or workflow in words → an analysis and an agentkit agent
-// (docs/agentkit.md) with test cases, which the person reviews, tests, runs and downloads. Built
-// agents live in ~/.agentmanager/built/<name>/ as ordinary agentkit folders.
+// The agent builder: a task or workflow in words → an agentkit agent (docs/agentkit.md), developed
+// in an agent session that works in the agent's folder: it writes the analysis, spec, instructions
+// and tests, and makes the changes the person asks for. The person tests, runs, packages and
+// downloads it here. Built agents live in ~/.agentmanager/built/<name>/ as ordinary agentkit folders.
 import { spawn } from 'node:child_process';
 import fs from 'node:fs';
 import path from 'node:path';
@@ -19,79 +20,126 @@ const err = (status, message) => Object.assign(new Error(message), { status });
 const now = () => new Date().toISOString();
 const slug = (s) => String(s ?? '').toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 40) || 'agent';
 
-export function designPrompt({ task, engine, attachments = [] }) {
+const DOCS = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', 'docs', 'agentkit.md');
+const ENGINES = ['claude', 'codex', 'muse'];
+
+/** The agent's name from the task: its first few words. */
+export function nameFrom(task) {
+  const words = String(task).toLowerCase().replace(/https?:\/\/\S+/g, ' ').split(/[^a-z0-9]+/).filter((w) => w && !STOP.has(w));
+  const n = slug(words.slice(0, 4).join('-')).slice(0, 32).replace(/-+$/, '');
+  return /^[a-z][a-z0-9-]{1,}$/.test(n) ? n : `agent-${n}`.replace(/-+$/, '').slice(0, 32);
+}
+const STOP = new Set(['a', 'an', 'the', 'to', 'of', 'for', 'and', 'or', 'in', 'on', 'by', 'with', 'from', 'that', 'this', 'it', 'is', 'are', 'be', 'i', 'we', 'my', 'our', 'want', 'need', 'agent', 'build', 'make', 'create', 'please', 'which', 'who']);
+
+/** The commands its session uses to check and try the agent. */
+export function agentkitCommands(dir) {
+  return { check: `${process.execPath} ${AGENTKIT} check`, run: `${process.execPath} ${AGENTKIT} run ${dir} --once` };
+}
+
+/** What its session may do without a permission prompt: check the agent, read the reference. */
+export function builderAllowedTools(dir) {
+  return [`Bash(${agentkitCommands(dir).check}:*)`, `Read(/${DOCS})`];
+}
+
+/**
+ * What a session that builds an agent is told (appended to its system prompt on every launch):
+ * the folder is the agent, the files it keeps, the format, and how to check and try it.
+ */
+export function builderPrompt({ dir, name, engine = 'claude' }) {
+  const cmd = agentkitCommands(dir);
   return [
-    'You design an autonomous agent that will run continuously on its own and do one job well. It runs through',
-    `${engine === 'claude' ? 'Claude Code' : engine} as its engine, uses tools through MCP servers, and is reached by people (chat) and other agents (A2A, MCP).`,
-    'From the task below, write the analysis and the agent. Be concrete; do not invent systems the task does not mention.',
+    `You are building an autonomous agent together with the person: an agentkit agent that runs on its own, continuously, and does one job well. This folder (${dir}) is the agent. Its name is "${name}"; keep it (it is the folder's name).`,
     '',
-    'Reply with one JSON object only:',
-    '{',
-    '  "analysis": {"problem": "<what the job is and why>", "inputs": ["<what it receives>"], "outputs": ["<what it produces>"], "risks": ["<what could go wrong, and what needs a person>"]},',
-    '  "name": "<lowercase-with-dashes, 2-40 chars>", "title": "<short>", "description": "<one line>",',
-    '  "goal": "<what is true when it has done its job, for each input; one or two sentences>",',
-    '  "instructions": "<Markdown: how to do the job, step by step; what to never do; when to ask>",',
-    '  "tools": [{"name": "<short id>", "why": "<what it needs it for>", "command": "<MCP server command, e.g. npx>", "args": ["…"], "env": {"VAR": "${VAR}"}}],',
-    '  "allow": ["<engine tool names it may use without asking, e.g. Read, Grep, mcp__<tool>__*>"],',
-    '  "approve": ["<tools that change things in the outside world and need a person\'s yes>"],',
-    '  "triggers": [{"every": "30m"} | {"cron": "0 9 * * 1-5"} | {"webhook": "/hooks/<name>"} | {"watch": "./inbox"}],',
-    '  "tests": [{"input": "<a realistic input>", "expect": "<what a good result does or contains>"}]',
-    '}',
+    'Keep these files current:',
+    '- agent.yaml: the spec (below).',
+    '- instructions.md: how to do the job, step by step; what it must never do; when it asks a person.',
+    '- tests.yaml: 3 to 8 test cases, a YAML list of {input, expect}: the normal case, an edge case, and a case it should refuse or escalate. The person runs them from the Built tab; each result is judged against `expect`.',
+    '- analysis.json: {"analysis": {"problem": "<the job and why>", "inputs": [...], "outputs": [...], "risks": ["<what could go wrong, what needs a person>"]}, "tools": [{"name": "<MCP server id>", "why": "<what for>"}]}. The person reads it in the Built tab; update it when the design changes.',
     '',
-    'Rules: 3 to 5 tests that cover the normal case, an edge case and a case it should refuse or escalate.',
-    'Only MCP servers that really exist and fit (leave "tools" empty when none is needed). Secrets only as "${VAR}".',
-    'Triggers only when the task implies running on its own (a schedule, events); chat-only agents have none.',
+    `agent.yaml has: name, title, description (one line), goal (what is true when it has done its job, for each input), instructions: instructions.md, engine: ${engine},`,
+    '  tools (MCP servers by id: {command, args, env}; only servers that really exist; secrets only as "${VAR}"),',
+    '  allow (engine tools it may use without asking, e.g. Read, Grep, "mcp__<id>__*"; to let it write files only under a folder: "Edit(./out/**)", which covers Write), approve (tools that change things in the outside world and need a person\'s yes),',
+    '  triggers (only when the task implies running on its own: {every: 30m}, {cron: "0 9 * * 1-5"}, {webhook: /hooks/<name>}, {watch: ./inbox}; a chat-only agent has none),',
+    '  loop: {plan: true, check: true, maxSteps: 4}, memory: true, interfaces: {http: {port: 0}, a2a: true, acp: true, mcp: true}.',
+    `The full reference: ${DOCS}.`,
     '',
-    '<task>',
-    task,
-    '</task>',
-    ...(attachments.length ? ['<attached_files>', ...attachments.map((a) => `--- ${a.name}\n${a.text}`), '</attached_files>'] : []),
+    'Write and edit these files with your file tools (Write, Edit), not with shell commands.',
+    `After every change, check it loads: ${cmd.check} ${dir}`,
+    `To try one input for real (it runs with its allowed tools; tools that need approval are refused): ${cmd.run} "<input>". Only with inputs that are safe to run for real.`,
+    'Be concrete; do not invent systems the task does not mention. When something only the person knows is missing (an account, a team name, a label set), ask.',
+    'The person tests, starts, packages and downloads it from the Built tab; you do not start it continuously or package it. When they ask for a change, make it in these files, check, and say in a sentence what changed.',
   ].join('\n');
 }
 
-export function judgePrompt({ goal, input, expect, result }) {
+/** The first message of a build session. */
+export function buildIntent({ task, name, engine }) {
+  return `Build the agent "${name}" (engine: ${engine}) for this task:\n\n${task}\n\nWrite analysis.json, agent.yaml, instructions.md and tests.yaml in this folder, check it, then tell me what it does and what I should decide or provide.`;
+}
+
+export function judgePrompt({ goal, input, expect, result, files = [] }) {
   return [
     "You check one test of an autonomous agent. Decide if the agent's result meets the expectation for the input.",
+    'The files it created or changed during the run are shown too: judge what it did from them, not only from what it says.',
     'Be strict about substance, lenient about wording. Reply with JSON only: {"pass": true|false, "why": "<one sentence>"}.',
     `<goal>\n${goal}\n</goal>`,
     `<input>\n${input}\n</input>`,
     `<expectation>\n${expect}\n</expectation>`,
     `<result>\n${result}\n</result>`,
+    ...(files.length ? ['<files_written>', ...files.map((f) => `--- ${f.path}${f.truncated ? ' (first part)' : ''}\n${f.text}`), '</files_written>'] : ['<files_written>\n(none)\n</files_written>']),
   ].join('\n');
 }
 
-/** agent.yaml text from a design. */
-export function yamlOf(d, engine) {
-  const tools = Object.fromEntries((d.tools ?? []).filter((t) => t?.name && t.command).map((t) => [slug(t.name), { command: t.command, ...(t.args?.length ? { args: t.args } : {}), ...(t.env && Object.keys(t.env).length ? { env: t.env } : {}) }]));
-  const doc = {
-    name: slug(d.name),
-    title: d.title || d.name,
-    description: d.description ?? '',
-    goal: d.goal,
-    instructions: 'instructions.md',
-    engine,
-    tools,
-    allow: d.allow ?? [],
-    approve: d.approve ?? [],
-    triggers: d.triggers ?? [],
-    loop: { plan: true, check: true, maxSteps: 4 },
-    memory: true,
-    interfaces: { http: { port: 0 }, a2a: true, acp: true, mcp: true },
+const SKIP = new Set(['.agentkit', '.git', 'node_modules', 'dist']);
+/** Files under `dir` (not its own state, git or build output) with when each last changed. */
+export function snapshot(dir, { max = 5000 } = {}) {
+  const seen = new Map();
+  const walk = (d) => {
+    let entries = [];
+    try {
+      entries = fs.readdirSync(d, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const e of entries) {
+      if (seen.size >= max) return;
+      const p = path.join(d, e.name);
+      if (e.isDirectory()) {
+        if (!SKIP.has(e.name)) walk(p);
+      } else if (e.isFile()) {
+        const st = fs.statSync(p, { throwIfNoEntry: false });
+        if (st) seen.set(p, `${st.mtimeMs}:${st.size}`);
+      }
+    }
   };
-  return YAML.stringify(doc, { lineWidth: 0 });
+  walk(dir);
+  return seen;
+}
+
+/** The text files created or changed since `before` (a snapshot), for the judge; a few, each capped. */
+export function filesWritten(dir, before, { root = dir, limit = 6, bytes = 4000 } = {}) {
+  const out = [];
+  for (const [p, sig] of snapshot(dir)) {
+    if (before.get(p) === sig || out.length >= limit) continue;
+    const buf = fs.readFileSync(p);
+    if (buf.subarray(0, 2000).includes(0)) continue; // binary
+    out.push({ path: path.relative(root, p), text: buf.subarray(0, bytes).toString('utf8'), truncated: buf.length > bytes });
+  }
+  return out;
 }
 
 export class Builder {
-  /** `oneShot(prompt)` answers a design or judge prompt (the daemon's writer engine). */
+  /** `oneShot(prompt)` answers a judge prompt (the daemon's writer engine). */
+  /** `sessions`: the daemon's agent sessions ({ create, get, tell, stop }); each built agent is developed in one. */
   /** `reportEnv()`: settings that make an agent started here report to this daemon. */
-  constructor({ oneShot, env = process.env, runTurn = engineTurn, pack = packageAgent, reportEnv = () => ({}) }) {
+  constructor({ oneShot, sessions, env = process.env, runTurn = engineTurn, pack = packageAgent, reportEnv = () => ({}) }) {
     this.reportEnv = reportEnv;
     this.oneShot = oneShot;
+    this.sessions = sessions;
     this.env = env;
     this.runTurn = runTurn;
     this.pack = pack;
     this.procs = new Map(); // name -> child process of `agentkit run`
-    this.pending = new Map(); // name -> what's in progress (designing, testing)
+    this.pending = new Map(); // name -> what's in progress (testing, packaging)
   }
 
   dir(name) {
@@ -128,59 +176,108 @@ export class Builder {
     const read = (f) => (fs.existsSync(path.join(dir, f)) ? fs.readFileSync(path.join(dir, f), 'utf8') : '');
     let spec = null;
     let specError = null;
-    try {
-      spec = loadAgent(dir, { env: this.env });
-    } catch (e) {
-      specError = e.message;
+    const yaml = read('agent.yaml');
+    if (yaml) {
+      try {
+        spec = loadAgent(dir, { env: this.env });
+      } catch (e) {
+        specError = e.message;
+      }
     }
     const p = this.procs.get(name);
     let runs = [];
     if (spec) runs = new Agent(spec, { env: this.env }).runs(20);
+    // Its session keeps analysis.json and tests.yaml current; read them as they are now.
+    let design = {};
+    try {
+      design = JSON.parse(read('analysis.json') || '{}');
+    } catch {}
+    let tests = m.tests ?? [];
+    try {
+      tests = (YAML.parse(read('tests.yaml') || '[]') ?? []).filter((t) => t?.input).map((t) => ({ input: String(t.input), expect: String(t.expect ?? '') }));
+    } catch {}
+    // Until its spec loads, the status follows the files: designing, then designed or needs fixing.
+    let status = m.status;
+    if (!yaml) status = 'designing';
+    else if (specError) status = 'needs-fixing';
+    else if (['designing', 'needs-fixing'].includes(status)) status = 'designed';
+    const s = m.session ? this.sessions?.get(m.session) : null;
+    // When its files last changed (its session edits them): results and executables from before are out of date.
+    const changedAt = new Date(Math.max(0, ...['agent.yaml', 'instructions.md', 'tests.yaml'].map((f) => fs.statSync(path.join(dir, f), { throwIfNoEntry: false })?.mtimeMs ?? 0))).toISOString();
     return {
       ...m,
       name,
+      status,
       title: spec?.title ?? name,
       description: spec?.description ?? '',
       dir,
-      yaml: read('agent.yaml'),
+      yaml,
       instructionsText: read('instructions.md'),
+      analysis: design.analysis ?? m.analysis ?? null,
+      tools: design.tools ?? m.tools ?? [],
+      tests,
       specError,
-      engine: spec?.engine ?? null,
+      engine: spec?.engine ?? m.engine ?? null,
       triggers: spec?.triggers.map((t) => t.label) ?? [],
       missingEnv: spec?.missingEnv ?? [],
       pending: this.pending.get(name) ?? null,
       running: p ? { pid: p.child.pid, url: p.url, since: p.since } : null,
+      session: s ? { id: s.id, name: s.name, status: s.status, running: s.runtime.running, busy: s.runtime.busy, attention: s.runtime.attention ?? s.runtime.waiting?.text ?? null } : null,
       runs,
       platforms: PLATFORMS.filter((x) => process.platform === 'darwin' || !x.startsWith('macos-')),
       host: HOST,
+      changedAt,
       // Executables built since the last edit that are still there.
       executables: Object.fromEntries(Object.entries(m.executables ?? {}).filter(([, x]) => fs.existsSync(path.join(dir, 'dist', x.file)))),
     };
   }
 
-  /** Design an agent from a task (one model call); writes the folder and returns it. */
-  async design({ task, engine = 'claude', attachments = [] }) {
+  /**
+   * Start building an agent for a task: its folder, and an agent session working in it that
+   * analyses the task and writes the agent (analysis, spec, instructions, tests). The person
+   * keeps developing it in that session.
+   */
+  design({ task, engine = 'claude', name, attachments, permissionMode, model }) {
     task = String(task ?? '').trim();
     if (!task) throw err(400, 'Describe the task or workflow');
-    if (!['claude', 'codex', 'muse'].includes(engine) && !/^acp:[a-z0-9-]+$/.test(engine)) throw err(400, 'engine: claude, codex, muse or acp:<name>');
-    const d = parseJsonReply(await this.oneShot(designPrompt({ task, engine, attachments })));
-    if (!d.goal || !d.name) throw err(502, 'The design was missing a name or goal; try again');
-    let name = slug(d.name);
-    for (let i = 2; fs.existsSync(path.join(root(), name)); i++) name = `${slug(d.name).slice(0, 36)}-${i}`;
-    const dir = path.join(root(), name);
+    if (!ENGINES.includes(engine) && !/^acp:[a-z0-9-]+$/.test(engine)) throw err(400, 'engine: claude, codex, muse or acp:<name>');
+    if (!this.sessions) throw err(503, 'Agent sessions are not available');
+    const want = name ? slug(name) : nameFrom(task);
+    if (!/^[a-z][a-z0-9-]{1,40}$/.test(want)) throw err(400, 'name: lowercase letters, digits and dashes, starting with a letter');
+    let n = want;
+    for (let i = 2; fs.existsSync(path.join(root(), n)); i++) n = `${want.slice(0, 36)}-${i}`;
+    const dir = path.join(root(), n);
     fs.mkdirSync(dir, { recursive: true });
-    fs.writeFileSync(path.join(dir, 'agent.yaml'), yamlOf({ ...d, name }, engine));
-    fs.writeFileSync(path.join(dir, 'instructions.md'), String(d.instructions ?? '').trim() + '\n');
-    const tests = (d.tests ?? []).filter((t) => t?.input).slice(0, 8).map((t) => ({ input: String(t.input), expect: String(t.expect ?? '') }));
-    fs.writeFileSync(path.join(dir, 'tests.yaml'), YAML.stringify(tests));
-    // Check it loads; a broken design is kept so the person can fix it.
-    let specError = null;
+    this.saveMeta(n, { task, engine, results: null, status: 'designing', createdAt: now() });
     try {
-      checkAgent(YAML.parse(fs.readFileSync(path.join(dir, 'agent.yaml'), 'utf8')), { dir, env: this.env });
+      const s = this.sessions.create({ name: n, dir, intent: buildIntent({ task, name: n, engine }), builds: { name: n, engine }, attachments, permissionMode, model });
+      this.saveMeta(n, { session: s.id });
     } catch (e) {
-      specError = e.message;
+      fs.rmSync(dir, { recursive: true, force: true });
+      throw e;
+    }
+    return this.view(n);
+  }
+
+  /**
+   * Ask its session for a change (typed in when it's idle; started if it's closed). An agent with
+   * no session yet (built before sessions, or its session deleted) gets a new one.
+   */
+  change(name, text) {
+    const dir = this.dir(name);
+    const m = this.meta(name);
+    if (!m) throw err(404, `No built agent "${name}"`);
+    text = String(text ?? '').trim();
+    const s = m.session ? this.sessions.get(m.session) : null;
+    if (s) {
+      if (!text) throw err(400, 'Say what to change');
+      this.sessions.tell(s.id, text);
+    } else {
+      const engine = this.view(name).engine ?? 'claude';
+      const intent = `This folder is the agent "${name}"${m.task ? `, built for this task:\n\n${m.task}\n\n` : '. '}Read agent.yaml, instructions.md and tests.yaml${fs.existsSync(path.join(dir, 'analysis.json')) ? ' and analysis.json' : ' and write analysis.json'}. ${text || 'Then tell me briefly what it does and wait for what to change.'}`;
+      const created = this.sessions.create({ name, dir, intent, builds: { name, engine } });
+      this.saveMeta(name, { session: created.id });
     }
-    this.saveMeta(name, { task, analysis: d.analysis ?? null, tools: (d.tools ?? []).map((t) => ({ name: t.name, why: t.why ?? '' })), tests, results: null, status: specError ? 'needs-fixing' : 'designed', createdAt: now() });
     return this.view(name);
   }
 
@@ -230,18 +327,22 @@ export class Builder {
       // Tests don't wait for people: approval tools are simply not available in them.
       const agent = new Agent({ ...spec, triggers: [], report: null }, { env: this.env, engineTurn: this.runTurn, approvals: 'deny' });
       const results = [];
+      // The judge sees what each run wrote in the agent's folders, not only what it says it did.
+      const roots = [...new Set([dir, spec.workdir])].filter((d, i, all) => !all.some((o, j) => j !== i && d.startsWith(o + path.sep)));
       for (const t of tests) {
+        const before = roots.map((d) => snapshot(d));
         const r = await agent.run(t.input, { source: 'test' });
+        const files = roots.flatMap((d, i) => filesWritten(d, before[i], { root: dir })).slice(0, 6);
         let verdict = { pass: false, why: 'The run failed' };
         if (r.status !== 'failed') {
           try {
-            const v = parseJsonReply(await this.oneShot(judgePrompt({ goal: spec.goal, input: t.input, expect: t.expect, result: r.result })));
+            const v = parseJsonReply(await this.oneShot(judgePrompt({ goal: spec.goal, input: t.input, expect: t.expect, result: r.result, files })));
             verdict = { pass: v.pass === true, why: String(v.why ?? '') };
           } catch (e) {
             verdict = { pass: false, why: `Could not judge: ${e.message}` };
           }
         }
-        results.push({ input: t.input, expect: t.expect, result: r.result, status: r.status, costUsd: r.costUsd, ...verdict });
+        results.push({ input: t.input, expect: t.expect, result: r.result, status: r.status, costUsd: r.costUsd, files: files.map((f) => f.path), ...verdict });
       }
       const passed = results.filter((r) => r.pass).length;
       this.saveMeta(name, { results: { at: now(), passed, total: results.length, list: results }, status: passed === results.length ? 'tested' : 'failing' });
@@ -326,6 +427,9 @@ export class Builder {
 
   remove(name) {
     this.stop(name);
+    // Its session works in the folder about to go; close it (the conversation is kept).
+    const sid = this.meta(name)?.session;
+    if (sid && this.sessions?.get(sid)) this.sessions.stop(sid);
     fs.rmSync(this.dir(name), { recursive: true, force: true });
     return { ok: true };
   }

package/src/manager.js

@@ -113,6 +113,7 @@ import { leadPrompt, subagents, teamDir, teamPrompt } from './teams.js';
 import { assistantDir, assistantPrompt, assistantSettings } from './assistant.js';
 import { learnCommand, memoryKey, memoryPrompt, memoryText } from './memory.js';
 import { runningClaude, scanClaudeSessions } from './sessions.js';
+import { builderAllowedTools, builderPrompt } from './builder.js';
 import {
   bugFromRef,
   extractRefs,
@@ -596,6 +597,7 @@ export class AgentManager extends EventEmitter {
     trigger,
     attachments,
     isolation,
+    builds,
   }) {
     intent = (intent ?? '').trim();
     const staged = stagedFiles(attachments);
@@ -648,6 +650,8 @@ export class AgentManager extends EventEmitter {
       ...(startedBy ? { startedBy } : {}),
       ...(trigger ? { trigger } : {}),
       ...(isolation ? { isolation } : {}),
+      // A session that develops an agent built here (builder.js): { name, engine }.
+      ...(builds ? { builds: { name: String(builds.name), engine: String(builds.engine ?? 'claude') } } : {}),
       name: name?.trim() || jiraKey || slug,
       slug,
       intent,
@@ -664,7 +668,7 @@ export class AgentManager extends EventEmitter {
       model: model || null,
       // Review the implementation plan before the agent implements it: null = no review.
       // Team members get their review from the team instead.
-      planReview: !general && !team && (planReview ?? this.config.planReview ?? false) ? { status: 'writing' } : null,
+      planReview: !general && !team && !builds && (planReview ?? this.config.planReview ?? false) ? { status: 'writing' } : null,
       status: 'preparing',
       desired: start ? 'running' : 'stopped',
       error: null,
@@ -1042,7 +1046,8 @@ export class AgentManager extends EventEmitter {
       if (this.config.inbox !== false) prompts.push(questionsPrompt(path.join(dir, path.basename(questionsPath(agent.id)))));
     }
     // SPEC.md before changing code, and PLAN.md kept as it goes (unless the plan review asks for the plan).
-    if (task && this.config.specs !== false) {
+    // A session building an agent keeps its analysis in the agent's folder instead.
+    if (task && this.config.specs !== false && !agent.builds) {
       fs.mkdirSync(briefDir(agent.id), { recursive: true });
       const dir = fs.realpathSync(briefDir(agent.id));
       writableDir ??= dir;
@@ -1061,6 +1066,11 @@ export class AgentManager extends EventEmitter {
       prompts.push(memoryPrompt(memoryText(memoryKey(agent))));
       allowedTools = [`Bash(${learnCommand()}:*)`];
     }
+    if (agent.builds && agent.workdir) {
+      prompts.push(builderPrompt({ dir: agent.workdir, name: agent.builds.name, engine: agent.builds.engine }));
+      // Checking the agent loads and reading the reference need no permission prompt.
+      allowedTools = [...(allowedTools ?? []), ...builderAllowedTools(agent.workdir)];
+    }
     if (agent.kind === 'assistant') {
       fs.mkdirSync(assistantDir(), { recursive: true });
       const dir = fs.realpathSync(assistantDir());
@@ -1153,6 +1163,14 @@ export class AgentManager extends EventEmitter {
     this.runtimes.set(agent.id, rt);
 
     proc.onData((data) => {
+      // Newer Claude Code blinks a ⏺ beside a pending tool call (while its permission prompt is
+      // up): drawn, not work. It goes to the terminal but doesn't keep the agent busy or fill the
+      // screen text the prompt is read from.
+      if (!data.replace(ANSI, '').replace(/[\s⏺]/g, '')) {
+        this.appendOutput(rt, data);
+        this.broadcast(rt, { t: 'o', d: data });
+        return;
+      }
       rt.linkScan = true;
       rt.lastOutputAt = Date.now();
       rt.tail = (rt.tail + data).slice(-4000);

package/src/server.js

@@ -525,9 +525,19 @@ export async function startServer({ port = PORT, host = HOST } = {}) {
   api.get('/agents/:id/memory', wrap((req) => memory.read(req.params.id)));
   api.put('/agents/:id/memory', wrap((req) => memory.write(req.params.id, req.body?.text)));
   api.post('/agents/:id/learn', wrap((req) => memory.learn(req.params.id, req.body?.text, { by: req.headers['x-agentmgr-agent'] ? undefined : 'you' })));
-  // The agent builder (agentkit agents designed from a task): design, edit, test, run, download.
-  // Agents started here report to this daemon (runs, cost, approvals).
-  const builder = new Builder({ oneShot: (prompt) => manager.oneShot(null, prompt, { ...manager.writerFor({}), timeoutMs: 300_000 }), reportEnv: () => ({ AGENTKIT_REPORT_URL: `http://127.0.0.1:${port}`, AGENTKIT_REPORT_TOKEN: reports.reportToken() }) });
+  // The agent builder (agentkit agents built from a task, each developed in an agent session
+  // working in its folder): build, change, test, run, package, download. Agents started here
+  // report to this daemon (runs, cost, approvals).
+  const sessions = {
+    create: (opts) => manager.create({ ...opts, worktree: false }),
+    get: (id) => {
+      const a = manager.get(id);
+      return a ? manager.view(a) : null;
+    },
+    tell: (id, text) => manager.tell(id, text),
+    stop: (id) => manager.stop(id).catch(() => {}),
+  };
+  const builder = new Builder({ sessions, oneShot: (prompt) => manager.oneShot(null, prompt, { ...manager.writerFor({}), timeoutMs: 300_000 }), reportEnv: () => ({ AGENTKIT_REPORT_URL: `http://127.0.0.1:${port}`, AGENTKIT_REPORT_TOKEN: reports.reportToken() }) });
   api.post('/agentkit/report', wrap((req) => reports.report(req.body ?? {})));
   api.get('/agentkit/agents', wrap(() => reports.list()));
   api.post('/agentkit/agents/:key/approvals/:id', wrap((req) => reports.decide(req.params.key, req.params.id, req.body?.allow === true, req.device ? `${req.device.name ?? 'a signed-in device'}` : 'you')));
@@ -535,7 +545,8 @@ export async function startServer({ port = PORT, host = HOST } = {}) {
   // What an agent elsewhere needs to report here (this computer only: it shows the token).
   api.get('/agentkit/connect', wrap(() => ({ token: reports.reportToken(), local: `http://127.0.0.1:${port}`, remote: remoteServer ? remote.remoteUrls(remotePort).map((u) => u.url) : [], cert: remoteServer ? remote.certificateFingerprint() : null })));
   api.get('/builder', wrap(() => builder.list()));
-  api.post('/builder', wrap((req) => builder.design({ task: req.body?.task, engine: req.body?.engine || 'claude', attachments: req.body?.attachments?.length ? manager.stagedText(req.body.attachments) : [] })));
+  api.post('/builder', wrap((req) => builder.design({ task: req.body?.task, engine: req.body?.engine || 'claude', name: req.body?.name || undefined, attachments: req.body?.attachments, permissionMode: req.body?.permissionMode || undefined, model: req.body?.model || undefined })));
+  api.post('/builder/:name/change', wrap((req) => builder.change(req.params.name, req.body?.text)));
   api.get('/builder/:name', wrap((req) => builder.view(req.params.name)));
   api.put('/builder/:name', wrap((req) => builder.update(req.params.name, req.body ?? {})));
   api.post('/builder/:name/test', wrap((req) => {