Mike/freno-dev
1
0
Fork 3
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity

marketing: FRE-199 fact-check verdict applied — first pair drafts/ → approved/

Browse Source 
Sponsor fact-check card (FRE-199, interaction 0101ee80) answered 2026-11-05
19:53Z: 'Approve both — move to approved/'. Status blockquotes updated to
record the verdict and the date; page bodies untouched.
This commit is contained in:
fixture
2026-11-05 19:54:45 +00:00
parent a58b25501a
commit 77e692273e
4 changed files with 6 additions and 4 deletions
Download Patch File Download Diff File Expand all files Collapse all files

88
marketing/approved/agent-done-signal/copy.md Normal file
View File

@@ -0,0 +1,88 @@
# How do you know when your coding agent is done?
> **Status: approved — sponsor fact-check passed 2026-11-05** (FRE-199 fact-check
> card, verdict: "Approve both — move to approved/"). Not published; a human
> places it on nook.freno.me from `approved/`.
> This page never names a product of ours and never names a competitor.
> Internal target: first page of the FRE-199 pair, Thu 2026-11-06.
Often, you don't — not from the terminal alone. A coding agent's turn can end in
silence: the prompt returns, the cursor blinks, and a finished turn looks exactly
like one that stalled, is still running, or is waiting on you. The fix is to stop
trusting silence and wire the two moments that matter — *the turn ended* and *the
agent needs you* — to something you will actually see.
## Why silence is the failure mode
A terminal coding agent ends a turn by printing a prompt. If you are in another
window, another room, or running several agents at once, nothing in that output
distinguishes "finished" from "blocked on a permission prompt" from "dead". The
task being done and you finding out are two different events, and the second one
has no default signal.
Practitioners keep rediscovering this. One operator running a self-hosted queue
of autonomous agent sessions described sessions that "finished their work but
never sent the done signal, and held their slots for hours" — their fix was to
derive "done" from git state plus an idle transcript instead of trusting the
agent's own signal. A public service post about a code-review plugin described
the mirror image: a green checkmark and "No findings" when the review had not
run at all. An empty result and a successful result rendered identically.
That is the trap in one sentence: **zero looks exactly like success.**
## What the turn-ending signal actually is
Claude Code gives you two hooks that bracket the moments worth surfacing:
- **`Stop`** fires when the agent finishes responding — the end of a turn.
- **`Notification`** fires when Claude Code sends a notification. A permission
prompt is one of these: the hook's payload carries a `notification_type` of
`permission_prompt` and a message like "Claude needs your permission".
- **`StopFailure`** fires instead of `Stop` when the turn ends on an API error —
rate limits, authentication problems, and the like.
All three can run a command of your choosing. The hooks reference documents the
events and includes a desktop-notification example built on macOS's `osascript`.
## What to check or do
1. **Wire turn-end to a notification you will actually notice.** A `Stop` hook
that calls `osascript -e 'display notification …'` (or your terminal's
notification escape) turns the silent prompt-return into a visible event.
A terminal bell is not this — it is mute the moment you switch windows.
2. **Route permission waits separately from completions.** The `Notification`
hook's payload tells you which kind it is. A permission wait means the agent
is *blocked on you*; treating it as "done" hides the one state that costs the
most time.
3. **Don't trust the exit signal alone.** Check the artifacts: `git status`,
`git log`, whether the transcript has gone idle. The queue operator's rule
generalises — a "done" that has to name what it is waiting on is a "done"
you can act on.
4. **Surface the failure path too.** A turn that ends on an API error fires
`StopFailure`, not `Stop` — an alert wired to the wrong one misses exactly
the runs that need attention.
One next step: take the agent command you run most often and give its end-of-turn
a notification you would notice from across the room. That single wire closes the
most expensive silence in the workflow.
---
## Fact-check table (not part of the page)
Every technical claim above, with its primary source. Claims about Claude Code's
behaviour come from its own documentation, re-read 2026-11-05.
| # | Claim in the page | Source |
|---|---|---|
| 1 | `Stop` fires when the agent finishes responding (end of a turn); hook cadence is "per turn: UserPromptSubmit, Stop, StopFailure" | Claude Code hooks reference — https://docs.anthropic.com/en/docs/claude-code/hooks |
| 2 | `Notification` fires "when Claude Code sends a notification"; example payload carries `notification_type: "permission_prompt"`, message "Claude needs your permission" | same hooks reference (Notification event section) |
| 3 | `StopFailure` "runs instead of Stop when the turn ends due to an API error" (rate limits, authentication) | same hooks reference (StopFailure section) |
| 4 | Hooks run a command of your choosing; a desktop-notification example using `osascript` is in the reference | same hooks reference (desktop notification example) |
| 5 | Operator anecdote: sessions that finished work but never signalled done, holding slots for hours; fix = derive done from git + idle transcript | r/ClaudeCode thread 1xjb3j0 ("Are you running a self-hosted queue of autonomous Claude Code sessions?", 2026-10-31), quoted in `drafts/listening.md` Scan 4 addendum. Quoted as one operator's described practice, not a measurement. |
| 6 | PSA anecdote: code-review plugin showed green check + "No findings" without running | r/ClaudeCode 1xmnz2c (2026-11-03), logged in `drafts/listening.md` Scan 6. |
| 7 | "Zero looks exactly like success" | Verbatim buyer phrasing, three independent instances (1xm09fs, 1xmnz2c, plus HN repeats) in `drafts/listening.md` Scans 5–8. Used as the problem's name, attributed to no one. |
**Ban compliance:** no product of ours named · no competitor named · no
superlatives · no benchmark numbers · no invented testimonials (anecdotes are
real threads, described without handles) · no price · no roadmap dates.

72
marketing/approved/agent-done-signal/rationale.md Normal file
View File

@@ -0,0 +1,72 @@
# Rationale — "How do you know when your coding agent is done?"
FRE-199 item 1, page 1 of the first pair. Drafted 2026-11-05 by CMO.
## The phrase
Primary: **"how do you know when your coding agent is done"** (variants: "agent
finished silently", "claude code waiting for permission" overlaps on the
blocked-half; this page owns the *done*-half).
Chosen by the FRE-199 selection rule: strongest buying intent we can answer
honestly without naming a product. It is on the standing phrase list
(`drafts/listening.md` §The phrase list: "how do I know when my agent is done").
## Why this phrase won the slot
- **Recurrence with independence.** The "zero looks exactly like success"
pattern appears in at least four separate sources across Scans 5–9: 1xm09fs,
the code-review PSA (1xmnz2c), and two HN commenters (fhub, sadilek), plus
the queue operator's done-signal workaround (1xjb3j0). Four independent
formulations of one pain in seven days is the strongest recurrence the
backlog shows.
- **Buying intent.** The people describing it are running agents unattended
right now and are losing time to the gap — they are past curiosity.
- **Answerable honestly, generically.** The mechanism (Stop / Notification /
StopFailure hooks) is documented in the agent's own reference; every claim in
the page traces to it. Nothing about our product is needed to answer it.
- **Wedge-aligned.** "An agent blocked is the most expensive kind of idle" —
the done-half of that sentence (idle you never learn about) is this page.
## Evidence trail
| Thread | Date | What it showed |
|---|---|---|
| r/ClaudeCode 1xjb3j0 — "self-hosted queue of autonomous Claude Code sessions" | 2026-10-31 | Sessions "finished their work but never sent the done signal, and held their slots for hours"; operator derives done from git + idle transcript; "a waiting one has to name what it's waiting on" |
| r/ClaudeCode 1xm09fs | 2026-11-02 | First "zero looks exactly like success" instance (verbatim buyer phrasing) |
| r/ClaudeCode 1xmnz2c — code-review plugin PSA | 2026-11-03 | Green check + "No findings" when the review never ran; third independent instance |
| HN comments (fhub, sadilek) | 2026-11-04/05 | Human-attention concurrency ceiling quantified twice more |
All rows live in `drafts/listening.md` (The-Nook local master line, single
canonical copy per FRE-748) with URLs and verbatim quotes.
## Gates before this page ships
1. **Sponsor fact-check** of the claims table in `copy.md` (owner: Michael
Freno). Page moves `pending/` → `approved/` on his read, per the marketing
tree's hard rule.
2. **CTO eyes on the agent-behaviour claims** — all four are sourced to the
Claude Code hooks reference re-read 2026-11-05, but anything asserted about
an agent's behaviour is CTO-verifyable, and the FRE-199 plan routes it to
him.
3. **Publish path:** `pending/` → `approved/` → a human places it on
nook.freno.me (blog route). Nothing posts itself.
## Ban compliance (FRE-199 + positioning.md rule 1)
- The Nook: not named. The notch, the island, the companion: not mentioned.
- Competitors (notch apps, agent monitors, Remote Control–style tools): not
named. Remote Control is not mentioned either — the page answers the done-half
without touching the away-from-desk half.
- Claude Code is named only as the subject whose documented behaviour the page
explains, with its own docs as the source — the same status the listening
phrase list already gives it. It is the agent, not a competitor.
- No superlatives, no benchmark numbers, no invented testimonials, no price,
no roadmap dates.
## Cadence note
This page and `agent-waiting-on-permission/` are the first pair. The queue
behind them (multiple-agents tracking, invisible-permission cluster) holds well
above the three-candidate floor, so the two-a-week cadence holds without
inventing phrases.

82
marketing/approved/agent-waiting-on-permission/copy.md Normal file
View File

@@ -0,0 +1,82 @@
# Why is my coding agent sitting on a permission prompt?
> **Status: approved — sponsor fact-check passed 2026-11-05** (FRE-199 fact-check
> card, verdict: "Approve both — move to approved/"). Not published; a human
> places it on nook.freno.me from `approved/`.
> This page never names a product of ours and never names a competitor.
> Internal target: second page of the FRE-199 pair, Fri 2026-11-07.
Because it tried to do something its permission settings don't allow, and the
default is to wait — indefinitely and quietly — for you. The prompt is not the
expensive part; the hour you spent not knowing it was waiting is. The way out is
not to approve faster, it's to make the prompts rare and the waiting visible.
## The mechanism
Claude Code's permission system decides, per tool call, whether to run, refuse,
or stop and ask. In its `default` mode, it prompts for permission on the first
use of each tool. Modes are set with `defaultMode` in the settings files, and a
session's rules come from allow / ask / deny lists evaluated in that order —
the first match wins.
You can see the whole rule set at any time with `/permissions`, which lists
every permission rule and the settings file each one came from. Rules can name
a specific use — `Bash(npm run build)` matches exactly that command — or a
wildcard, like `Bash(git log *)`.
So the prompt you came back to an hour later is not a malfunction. It is the
system working as configured, on a call your rules never covered — and the
"waiting" state being invisible is what turned ten seconds of approval into a
lost hour.
## What to check or do
1. **Read the prompt before automating it away.** It names the tool and the
input. The right response to "it keeps asking" is usually a rule, not a
wider mode.
2. **Allowlist the undoable, prompt on the irreversible.** Reads, tests, and
status commands are safe to allow — `git` is the undo for edits. Anything
that reaches another person or another system — network calls, deletes,
deploys — is worth keeping on ask. Rule syntax is in the permission docs;
`/permissions` shows what you already have.
3. **Consider `acceptEdits` before anything broader.** It auto-accepts file
edits and common filesystem commands inside the working directory. That is
usually the difference between ten prompts a session and two — without
handing over network or delete.
4. **Bound the blast radius instead of removing the gate.** If you do widen
what runs unattended, do it where a mistake is recoverable: a worktree per
task, commits pushed early, nothing irreversible in reach. Operators who run
agents unattended describe exactly this split — free hand on what git can
undo, confirmation on what it can't.
5. **Make the wait visible.** Claude Code fires a `Notification` hook when it
sends a notification, and a permission prompt is one — the payload carries a
`notification_type` of `permission_prompt`. A hook on that event, wired to a
desktop notification you'd see from another window, turns the silent wait
back into a ten-second approval.
One next step: run `/permissions` today and add allow rules for the three
commands you find yourself approving most. The prompts that remain will be the
ones that deserve a read.
---
## Fact-check table (not part of the page)
Every technical claim above, with its primary source. Claims about Claude
Code's behaviour come from its own documentation, re-read 2026-11-05.
| # | Claim in the page | Source |
|---|---|---|
| 1 | In `default` mode Claude Code "prompts for permission on first use of each tool" | Claude Code permissions doc — https://docs.anthropic.com/en/docs/claude-code/permissions (Permission modes table) |
| 2 | `defaultMode` in settings files sets the default mode for new sessions | same permissions doc (Permission modes section) |
| 3 | Rules are evaluated deny → ask → allow, first match wins | same permissions doc (Permission rule syntax) |
| 4 | `/permissions` lists all permission rules and the settings.json each comes from | same permissions doc (Manage permissions) |
| 5 | `Bash(npm run build)` matches the exact command; `Bash(git log *)` wildcard form | same permissions doc (Use specifiers for fine-grained control) |
| 6 | `acceptEdits` "automatically accepts file edits and common filesystem commands such as mkdir, touch, mv, cp for paths in the working directory" | same permissions doc (Permission modes table) |
| 7 | A `Notification` hook fires when Claude Code sends a notification; permission prompts carry `notification_type: "permission_prompt"` and a message like "Claude needs your permission" | Claude Code hooks reference — https://docs.anthropic.com/en/docs/claude-code/hooks (Notification event) |
| 8 | Undo-split practice ("free hand on what git can undo, confirmation on what it can't") | r/ClaudeCode 1xkoz06 (2026-10-31, u/tomm3hshipp thread), commenter's described practice, logged in `drafts/listening.md` Scan 3 addendum. Described as one operator's approach, not a rule. |
| 9 | The 55-minutes-lost framing | r/ClaudeAI 1xhbc71 (2026-10-28): "coming back an hour later to find it's been sitting on a permission prompt for 55 minutes". Used as the problem's shape, not quoted as a person. |
**Ban compliance:** no product of ours named · no competitor named · no
superlatives · no benchmark numbers · no invented testimonials · no price · no
roadmap dates.

77
marketing/approved/agent-waiting-on-permission/rationale.md Normal file
View File

@@ -0,0 +1,77 @@
# Rationale — "Why is my coding agent sitting on a permission prompt?"
FRE-199 item 1, page 2 of the first pair. Drafted 2026-11-05 by CMO.
## The phrase
Primary: **"claude code waiting for permission"** and the away-from-desk variant
("approvals when you're away from the computer"). First phrase on the standing
list (`drafts/listening.md` §The phrase list).
## Why this phrase won the slot
- **The strongest single thread in the backlog.** r/ClaudeAI 1xhbc71 (2026-10-28,
47 comments and moving) asks the buying question outright: kicked off a long
task, came back an hour later, agent had been sitting on a permission prompt
for 55 minutes. The thread's own answers (remote control, tmux+SSH,
skip-permissions, allowlists) prove demand; none of them makes the wait
visible at the machine — that is the honest gap this page answers without
naming anyone.
- **The week's objection vocabulary.** Scans 1–9 keep returning "the model keeps
handing control back" and "stops and waits for me" — permission friction is
the category's core complaint, not a niche one.
- **Recurring independent accounts.** The invisible-permission theme has three
independent accounts in one week (1xksutq — gh used without a visible prompt;
1xkejsp's Linux panel; the scheduled-tasks silent-stall finding), so the
search demand is not one loud thread.
- **Wedge-aligned.** This is the literal wedge sentence's territory — "an agent
blocked on a permission prompt is the most expensive kind of idle" — answered
with the agent's own documented mechanism.
## Deliberate scoping
This page owns the **blocked-half** of the approval problem (why prompts happen,
how to make them rare, how to make the wait visible at the machine). The
**away-half** (controlling a remote agent from elsewhere) is a different phrase,
a different page, and one where the honest answer is dominated by the agent
vendor's own remote feature — the page deliberately does not go there
(`drafts/listening.md` Scan 1 category intel #1).
## Evidence trail
| Thread | Date | What it showed |
|---|---|---|
| r/ClaudeAI 1xhbc71 — "How do you handle Claude Code approvals when you're away from your computer?" | 2026-10-28 | 55-minute wait on a permission prompt; 47 comments of demand; "what's still annoying about your setup?" |
| r/ClaudeCode 1xkoz06 — "How permissive are you with AI and for how long?" | 2026-10-31 | The undo-split: "file edits, tests and branches get a free hand, since git is the undo. Anything that reaches another person … stays on confirm" |
| r/ClaudeCode 1xksutq — gh used without visible prompt | 2026-11-01 | Third independent invisible-permission account of the week |
| r/ClaudeCode 1xkejsp — Linux panel app | 2026-10-31 | Per-session "Needs You" differentiation shipping elsewhere; the need is real and cross-platform |
All rows live in `drafts/listening.md` with URLs and verbatim quotes.
## Gates before this page ships
1. **Sponsor fact-check** of the claims table in `copy.md` (owner: Michael
Freno); page moves `pending/` → `approved/` on his read.
2. **CTO eyes on the agent-behaviour claims** — all eight doc-sourced claims
re-read 2026-11-05; the FRE-199 plan routes anything asserted about an
agent's behaviour to the CTO.
3. **Publish path:** `pending/` → `approved/` → a human places it on
nook.freno.me (blog route). Nothing posts itself.
## Ban compliance (FRE-199 + positioning.md rule 1)
- The Nook: not named; notch/island/companion not mentioned.
- Competitors: not named — including the agent vendor's remote feature, which
the page never needs to mention because it stays on the at-the-machine half.
- Claude Code is named only as the subject whose documented permission system
the page explains, with its own docs as the source — same status the
listening phrase list already gives it.
- No superlatives, no benchmark numbers, no invented testimonials, no price,
no roadmap dates.
## Cadence note
Second page of the first pair. Queue behind it: multi-agent tracking ("How do
you keep track of multiple coding agents running in parallel?", 1xm6frp,
2026-11-03) and the invisible-permission cluster — the queue holds above the
three-candidate floor, so the two-a-week cadence holds.