@monster-orange/den 0.4.6 → 0.4.7

package/CHANGELOG.md

@@ -4,6 +4,72 @@ All notable changes to Den are documented here. Each release lists the
 config and manifest changes a distribution must make to move to it under
 **Migrations**.
 
+## [0.4.7] - 2026-11-07
+
+Agents read slices, wait in the background and hand back plainly (den#5,
+the default-pack guardrails issue). Every persona in Den's default pack
+gets Den's shared instructions and, on Claude Code, Den's hooks, with no
+setup. `doctor` warns about polling loops it sees in the local dev metrics.
+
+### Added
+
+- **The Stop hook reads every last message.** With a `## Hand-back`
+  heading it checks the whole hand-back, as before. Any other last message
+  gets the plain-writing check: every ID explained. It still never blocks
+  twice in a row.
+- **`URL: none` in a hand-back.** Work with no page (a CLI change, a
+  refused request) says `URL: none`, with a reason if it likes. An empty
+  or missing URL still fails.
+
+- **`down --json` and `web down --json`.** The clean-up steps answer in
+  JSON like every other onboarding step: `{ ok, workspace, services }` and
+  `{ ok, url, port, running, stopped }`. Both are safe to re-run.
+
+- **Hooks for default-pack agents.** A Claude Code agent from Den's default
+  pack runs with Den's own hooks, in its own `--settings` file (never your
+  `~/.claude`). A `PreToolUse` hook on Bash and Read blocks reading all of
+  a log or a large file into the conversation (`cat`, `less`, `tail` from
+  a line such as `tail +1`, a Read with no limit; a plain `tail` passes) and says to read a slice or use a
+  subagent. It blocks a foreground `sleep`, alone or in an `until`/`while`/
+  `for` loop, and says to run in the background or use a wait primitive.
+  It blocks nothing else.
+- **Shared persona instructions.** Every default-pack persona's role prompt
+  ends with Den's `guardrails/instructions.md`: write plainly, in short
+  sentences; say what every issue or ID is; ask each decision as a numbered
+  yes/no question; no caveat sections; and the hand-back template (URL,
+  machine, branch, what changed, what to click, decisions).
+- **The hand-back check.** `<cli> agents handback-check <file|->` rejects a
+  hand-back with a missing part, an unexplained ID, or a decision that is
+  not a numbered yes/no question, and says what to fix. A `Stop` hook runs
+  the same check on a turn that ends with a `Hand-back` heading, and sends
+  Claude back to fix it once.
+- **doctor warns about polling loops.** It reads the end of the local
+  `.dev-metrics/events.jsonl` (at most 8 MB) and warns when one command,
+  run from one place, ran more than 600 times in an hour:
+  `looks like a polling loop: status in services/api, 1200 calls in an hour (…)`.
+  It is local and sends nothing.
+- **Each dev-metrics line records `cwd`**, relative to the distribution root
+  (`.` at the root, `outside` elsewhere), never an absolute or home path.
+  Like every field, it is sent only when you opt in.
+
+### Metrics (before → after)
+
+- Polling loops a week: 18,600 → under 100 expected, since the hook blocks
+  them. The "after" is counted on the candidate's first week.
+- Incomplete hand-backs: not measured → 0 for default-pack agents (the Stop
+  hook sends them back). The candidate's first run sets the baseline.
+- Hand-backs with an unexplained ID: no baseline → 0 for default-pack
+  agents. The candidate's first run sets the baseline.
+- doctor on a replay of a three-day polling burst: no warning → it warns.
+
+### Migrations
+
+- None needed. To turn the guardrails off for Den's pack, set
+  `agents.default_pack: { hooks: false, instructions: false }`. To turn
+  them on for your own pack, write its `persona_packs` entry as
+  `{ path: <dir>, hooks: true, instructions: true }`. A persona's
+  `den_hooks` / `den_instructions` front matter wins over its pack's.
+
 ## [0.4.6] - 2026-11-07
 
 Den in five minutes, set up by your own agent (ON-2, with ON-4's dry run).

package/README.md

@@ -10,8 +10,8 @@
 </p>
 
 <picture>
-  <source media="(prefers-color-scheme: dark)" srcset="docs/images/0.4.6/hero-dark.png">
-  <img src="docs/images/0.4.6/hero-light.png" width="100%" alt="Den's Graph page: the demo workspace's services grouped by application, all healthy, with the status chip and the left rail">
+  <source media="(prefers-color-scheme: dark)" srcset="docs/images/0.4.7/hero-dark.png">
+  <img src="docs/images/0.4.7/hero-light.png" width="100%" alt="Den's Graph page: the demo workspace's services grouped by application, all healthy, with the status chip and the left rail">
 </picture>
 
 ## Set up by your agent
@@ -38,7 +38,7 @@ It doesn't replace your tools. Your repos, Docker, your test runners, your secre
 yours. Den connects them and turns on good practice from the start.
 
 <p align="center">
-  <img src="docs/images/0.4.6/up.gif" width="100%" alt="make up in the Graph page: every stack down, then demo-api, demo-web and demo-notes come up in dependency order until the status chip reads All 3 healthy">
+  <img src="docs/images/0.4.7/up.gif" width="100%" alt="make up in the Graph page: every stack down, then demo-api, demo-web and demo-notes come up in dependency order until the status chip reads All 3 healthy">
 </p>
 
 ## How it helps
@@ -68,10 +68,10 @@ yours. Den connects them and turns on good practice from the start.
   lives in your own repo.
 
 <p align="center">
-  <img src="docs/images/0.4.6/agents.png" width="49%" alt="The Agents tab: the demo workspace's sessions on the left, and one open in a terminal pane on the right, running demo-api's test and then the service">
-  <img src="docs/images/0.4.6/workspaces.png" width="49%" alt="The Workspaces page: the demo workspace's repos with their health, mode and Start, Stop, Restart and Logs actions">
-  <img src="docs/images/0.4.6/status-drawer.png" width="49%" alt="The status drawer: nothing needs attention, and every service in the demo workspace, by application, with its latency">
-  <img src="docs/images/0.4.6/edge.png" width="49%" alt="The Edge page: the edge container up, its ports and TLS, and every route it serves, Den's own and each stack's, with its upstream">
+  <img src="docs/images/0.4.7/agents.png" width="49%" alt="The Agents tab: the demo workspace's sessions on the left, and one open in a terminal pane on the right, running demo-api's test and then the service">
+  <img src="docs/images/0.4.7/workspaces.png" width="49%" alt="The Workspaces page: the demo workspace's repos with their health, mode and Start, Stop, Restart and Logs actions">
+  <img src="docs/images/0.4.7/status-drawer.png" width="49%" alt="The status drawer: nothing needs attention, and every service in the demo workspace, by application, with its latency">
+  <img src="docs/images/0.4.7/edge.png" width="49%" alt="The Edge page: the edge container up, its ports and TLS, and every route it serves, Den's own and each stack's, with its upstream">
 </p>
 
 ## Get started

package/docs/distributions.md

@@ -87,6 +87,8 @@ question for the person (`ask`, sometimes with `choices`).
 | `<cli> web up --no-open --json`                            | `{ ok, url, port, version? }`                                                |
 | `<cli> doctor --json`                                      | `{ ok, checks: [{ id, status, detail, url?, port?, fix?, ask? }] }`          |
 | `<cli> mcp connect --runtime <runtime> --json`             | `{ ok, server, clients: [{ id, ok, said, file?, changed? }], restart, web }` |
+| `<cli> down <repo> --json`                                 | `{ ok, workspace, services, all? }`                                          |
+| `<cli> web down --json`                                    | `{ ok, url, port, running, stopped }`                                        |
 
 ### repo add
 
@@ -122,6 +124,10 @@ question for the person (`ask`, sometimes with `choices`).
 
 ### up, doctor and mcp connect
 
+- `down --json` and `web down --json` are the clean-up steps. Each is safe
+  to re-run: `web down` answers `stopped: false` when the server wasn't
+  running, and `ok` is true once nothing answers on its port.
+
 - `up --json` runs `up` as usual, then reports each service it touched:
   `result` is `started`, `already-running`, `failed` or `skipped`, and
   `health` is the service's health after it started (a service with a
@@ -684,6 +690,18 @@ one is started (see Sessions).
 server, Den's MCP) and answers with one JSON object: see
 [Set up by your agent](#up-doctor-and-mcp-connect).
 
+doctor also reads the end of the local `.dev-metrics/events.jsonl` (at
+most 8 MB of it, however big the file) and warns when one command, run
+from one place, ran more than 600 times in an hour. That is almost always
+an agent polling. It is a warning, never a failure, and nothing is sent
+(see [Dev metrics](#dev-metrics-local-unless-you-opt-in)):
+
+```
+Acme doctor: dev-metrics (local, never sent)
+
+  ⚠ looks like a polling loop: status in services/api, 1200 calls in an hour (2026-11-04T09:00:00Z–2026-11-04T09:59:57Z)
+```
+
 ## den.yml: the product profile
 
 Every runtime name derives from `product.name`. Set only what you want to
@@ -2012,6 +2030,7 @@ server scoped to its workspace.
 <cli> agents resume <id> [-w <ws>]
 <cli> agents personas [--json]
 <cli> agents doctor [-w <ws>] [--json]  # can each runtime run here, and why not
+<cli> agents handback-check <file|->    # is a hand-back complete and plain (see Guardrails)
 <cli> sessions attach <ws>:<id>         # its terminal; ctrl-] detaches
 ```
 
@@ -2215,6 +2234,8 @@ standing: true # starts with its workspace (later slices)
 context: [docs/specs, the design system] # what to read first
 runtime: generic # default den-claude
 permission_mode: plan # den-claude only; default `default`
+den_hooks: false # Den's guardrail hooks for this persona (see Guardrails)
+den_instructions: false # Den's shared instructions for this persona
 argv: ["some-cli", "--model", "{model}", "--mcp-config", "{mcp_config}"]
 ---
 
@@ -2236,6 +2257,104 @@ used without converting them. Files without front matter (a README) are
 skipped; two files with one id in a pack, or a pack that isn't a directory,
 are errors naming the file or the key.
 
+### Guardrails: hooks, shared instructions, hand-backs
+
+Every persona in Den's default pack gets two things with no setup: Den's
+**shared persona instructions** and, on den-claude, Den's **hooks**. Both
+are Den's own files, in `src/shared/agents/guardrails/` of the package.
+
+**Shared instructions** (`instructions.md`) are appended to the role prompt
+(den-claude's `--append-system-prompt`; any runtime that takes the role
+prompt gets them). They say:
+
+- write to people plainly, in short sentences;
+- never name an issue or ID without saying what it is;
+- ask each decision as a numbered yes/no question;
+- no caveat sections, and nothing the person doesn't need in order to act;
+- read a slice of a log, or hand it to a subagent; don't poll with `sleep`;
+- end a hand-back with the template below.
+
+**Hooks** (`hooks.json`, a Claude Code settings fragment) go in the agent's
+own settings file, `--settings <stateDir>/agent-files/<id>/settings.json`.
+Den never writes your `~/.claude`; your own hooks still run.
+
+- `PreToolUse` on `Bash|Read` (`pretooluse.mjs`, plain Node, no imports)
+  blocks, with a reason Claude sees (exit 2):
+  - reading all of a log or a large file into the conversation: a `Read`
+    with no `limit`, or `cat`, `less`, or `tail` from a line (`tail +1`,
+    `tail -n +1`), whose output reaches the conversation. A log is `*.log` or `*.log.<N>`, a `.jsonl` under
+    `.dev-metrics/`, or a `.jsonl` under `.claude/projects/` (a transcript).
+    Large is over 256 KB. `cat x.log | grep …`, `cat x.log > y`, a plain
+    `tail x.log` (10 lines) and `tail -n 100 x.log` pass. The reason says to read a slice or hand the
+    file to a subagent.
+  - `sleep` in the foreground, alone or in an `until …; do sleep …; done`,
+    `while` or `for` loop. A Bash call with `run_in_background`, and
+    `sleep … &`, pass. The reason says to run in the background or use a
+    wait primitive. Recent Claude Code versions have their own sleep guard,
+    which answers first (and also stops `sleep … &`). The sleep is blocked
+    either way; Den's hook covers runtimes and versions without that guard.
+  - Nothing else. Quoted text, heredoc bodies and other tools always pass,
+    and a hook that can't read its input lets the call through.
+- `Stop` (`stop-hook.ts`) checks a turn's last message, which is what the
+  person reads. With a `Hand-back` heading it gets the whole hand-back
+  check; any other message gets the plain-writing part only (every ID
+  explained). If the check fails, Claude is told what to fix and keeps
+  going (Claude Code's `decision: "block"`). It never blocks twice in a
+  row (`stop_hook_active`), so it can't loop. Den adds no `SubagentStop` hook: a subagent reports to its parent
+  agent, not to a person.
+
+**The hand-back template**, which the check enforces:
+
+```markdown
+## Hand-back
+
+- URL: <the full link the person opens, with https://>
+- Machine: <the machine it runs on>
+- Branch: <the branch>
+- What changed: <what is different now>
+- What to click: <the steps to see it working>
+- Decisions:
+  1. <a question the person answers yes or no>?
+```
+
+`<cli> agents handback-check <file|-> [--json]` runs the same check on a
+file or stdin: exit 0 when the hand-back passes, 1 with each problem. It
+rejects a hand-back when:
+
+- a part is missing or empty. A part is a line starting with its label and
+  a colon (bold is fine), or a heading that is its label. URL must hold a
+  link (`://`), or say `none` for work with no page (`URL: none — a CLI
+change` is fine). `Decisions: none` is allowed.
+- an ID is bare. An ID is `#<digits>`, or 1 to 4 capitals, an optional `-`,
+  digits and an optional `.<digits>` (`R12`, `AG-14`, `KB-4.1`). Links,
+  `inline code`, code blocks, and the URL and Branch parts are not checked.
+  An ID is explained (glossed) when
+  1. a parenthetical of two or more words follows it: `#5 (the hooks issue)`;
+  2. a colon or a spaced dash and two or more words follow it:
+     `R12: plain writing`;
+  3. it sits in a parenthetical of IDs only, right after a word:
+     `plain writing (R12)`, `the issues (#5, #6)`;
+  4. or the same ID was explained earlier in the text.
+- a decision isn't a numbered yes/no question: each item must be numbered
+  (`1.` or `1)`), end in `?`, not start with what, which, how, why, when,
+  where or who, and not offer a choice (`or`).
+
+**Turning them off or on.** They are on for Den's default pack and off for
+your own packs. A pack's setting applies to each of its personas; a
+persona's front matter (`den_hooks`, `den_instructions`) wins over it:
+
+```yaml
+agents:
+  default_pack: { hooks: false } # Den's pack: no hooks, instructions kept
+  persona_packs:
+    - personas # your pack: neither
+    - { path: more-personas, hooks: true, instructions: true } # both
+```
+
+A persona of yours that replaces a default one (same id) takes your
+pack's setting, not Den's pack's. Anything but `true` or `false`, or an
+unknown key, is an error naming the key.
+
 ### Runtimes
 
 `<cli> doctor` lists the runtime kind. Den knows the runtimes in its
@@ -2418,6 +2537,11 @@ metrics:
   share: true
 ```
 
+Each line also records `cwd`: where the command ran, relative to the
+distribution root (`.` for the root), or `outside` for anywhere else. It is
+never an absolute or home path. [`<cli> doctor`](#doctor) uses it to warn
+about polling loops.
+
 Only the boolean `true` counts. With it, and a Sentry DSN in
 `DEV_METRICS_SENTRY_DSN` (or a synced `dev-metrics.config`), each line is
 also sent, best effort. A DSN on its own never sends. `CI=true` and

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@monster-orange/den",
-  "version": "0.4.6",
+  "version": "0.4.7",
   "description": "Den: a local multi-repo dev orchestrator, HTTPS edge and E2E harness",
   "type": "module",
   "bin": {

package/skills/install-den/SKILL.md

@@ -65,8 +65,8 @@ person (`ask`, sometimes with `choices`).
      in `package.json`. `--sidecar` asks for this explicitly, and fails if the repo has its own manifest.
    - If you can see which port the app listens on, add `--health http://localhost:<port>/`. Den then checks that it
      answers.
-2. If the answer has `ask` and `choices`, Den couldn't tell how the repo starts, and it wrote nothing. Ask the person
-   **one** question: the `ask` text, with the choices numbered. Then re-run with their answer:
+2. If the answer has `ask`, Den couldn't tell how the repo starts, and it wrote nothing. Ask the person **one**
+   question: the `ask` text, with any `choices` numbered (there may be none). Then re-run with their answer:
    `./bin/<name> repo add <repo> --run "<their command>" --json`.
 3. The answer names the repo (`repo`), the workspace it joined (`workspace`) and where its manifest is (`manifest`).
    A workspace is Den's name for a set of repos that run together. The first one is called `default`.

package/src/shared/agents/den-claude.ts

@@ -15,6 +15,10 @@
  *   `<state>/sessions/**`. It binds a
  *   cooperating agent only: the agent runs as the same OS user, so nothing
  *   stops one that ignores its permission config from reading them.
+ * - Den's guardrail hooks (den#5, guardrails.ts), when the persona's
+ *   guardrails include them: the same settings file carries
+ *   guardrails/hooks.json's `hooks` (PreToolUse on Bash and Read, and Stop),
+ *   alongside any hooks the user has; Den never writes ~/.claude.
  * - Each launch picks a fresh conversation id (--session-id); resume
  *   continues it with --resume <id>, in the same cwd, with the same MCP.
  * - Permission prompts stay in the terminal (approvals: "terminal"):
@@ -41,6 +45,7 @@ import * as fs from "fs";
 import * as path from "path";
 import { configuredRuntimeBin } from "../den-config.js";
 import { rolePrompt } from "./personas.js";
+import { guardrailHooks } from "./guardrails.js";
 import {
   LaunchError,
   mcpConfigJson,
@@ -221,7 +226,8 @@ function common(input: LaunchInput): {
 } {
   const file = mcpConfigPath(input);
   const mode = permissionMode(input);
-  const settings = input.stateDir ? settingsPath(input) : null;
+  const hooks = input.persona.guardrails?.hooks ? guardrailHooks() : null;
+  const settings = input.stateDir || hooks ? settingsPath(input) : null;
   return {
     argv: [
       "--mcp-config",
@@ -241,13 +247,21 @@ function common(input: LaunchInput): {
     ],
     files: {
       [file]: mcpConfigJson(input.mcp),
-      ...(settings && input.stateDir
+      ...(settings
         ? {
             [settings]: `${JSON.stringify(
               {
-                permissions: {
-                  deny: stateDirDenyRules(input.stateDir, input.env?.HOME),
-                },
+                ...(input.stateDir
+                  ? {
+                      permissions: {
+                        deny: stateDirDenyRules(
+                          input.stateDir,
+                          input.env?.HOME,
+                        ),
+                      },
+                    }
+                  : {}),
+                ...(hooks ? { hooks } : {}),
               },
               null,
               2,

package/src/shared/agents/guardrails/hooks.json

@@ -0,0 +1,27 @@
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash|Read",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "{pretooluse}",
+            "timeout": 10
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "{stop}",
+            "timeout": 30
+          }
+        ]
+      }
+    ]
+  }
+}

package/src/shared/agents/guardrails/instructions.md

@@ -0,0 +1,39 @@
+## How you work and write (every Den persona)
+
+### Writing to people
+
+- Write plainly. Use short sentences.
+- Never name an issue or an ID without saying what it is. Write "#5 (the
+  hooks issue)" or "the plain-writing rule (R12)", never a bare "#5" or "R12".
+- Ask each decision as a numbered yes/no question. One question per number.
+- No caveat sections. Leave out anything the person doesn't need in order to
+  act.
+
+### Reading and waiting
+
+- Don't read a whole log or a large file into the conversation. Read a slice
+  (`tail -n 100`, `grep -n`), or hand the file to a subagent and ask for the
+  conclusion.
+- Don't poll with `sleep` or `until …; do sleep …; done`. Run long work in the
+  background and wait to be told it ended, or use a wait primitive.
+
+### Handing work back
+
+When you hand work back to a person, end with this, filled in. Den checks it:
+a hand-back with a missing part, an unexplained ID, or a decision that is not
+a numbered yes/no question is sent back to you to fix.
+
+```
+## Hand-back
+- URL: <the full link the person opens, with https://>
+- Machine: <the machine it runs on>
+- Branch: <the branch>
+- What changed: <what is different now, in a sentence or two>
+- What to click: <the steps to see it working>
+- Decisions:
+  1. <a question the person answers yes or no>?
+```
+
+Write "Decisions: none" when there are none, and "URL: none" (with a short
+reason) when the work has no page to open. Every message you end a turn
+with is read by a person, hand-back or not: explain each ID in it.