Permissions that wait
How Narsil insists once when a permission, a question or a plan has waited five minutes for you, and why it checks on a heartbeat instead of setting a timer.
What it does
Claude often stops in the middle of a turn to ask you something: permission to run a tool, a question, or a plan to approve. Narsil tells you at that moment, as the earlier guides show (the “TE NECESITA” state, the voice, the floating window).
But that first alert is easy to miss. You were in another window, or you saw it and meant to come back. Five minutes later, if the same thing is still waiting, Narsil insists once:
Sigo esperándote
Sigo esperándote desde hace 5 min: pido permiso para usar Bash.
“I am still waiting for you, for 5 minutes now: I am asking permission to use Bash.” The second half names what waits, so a question reads “tengo una pregunta para ti” (“I have a question for you”) and a plan “tengo un plan para que lo apruebes” (“I have a plan for you to approve”).
The insistence goes out as a question alert: in the floating window, aloud with one of the stillWaiting phrases (“Sigo aquí, esperándote.”, “I am still here, waiting for you”), and to the phone under the rules of the voice and alerts guide. The README adds the detail that sets it apart from the first alert: it shows “aunque estés mirando Claude”, even while you are looking at Claude.
It happens once per wait. If you still do not answer, Narsil does not keep insisting.
How it works inside
A wait is one module variable
What waits is held in one variable in hooks/register.tsx:
let waiting: { since: number; what: string; isNudged: boolean } | null = null
startWaiting($, what) fills it with the current time from $.clock.now(); stopWaiting() sets it back to null. A module variable is enough: the wait belongs to this conversation, and nobody else reads it.
What starts a wait
Three places call startWaiting, the same three that raise the first alert:
classic.PermissionRequest, a permission dialog. The first guide explains why Narsil listens here and not totool.check: the engine raises it only when it is about to show you the dialog. The hook still skips it when a settings hook already answered (result.decisionis set) or the mode isbypassPermissions.tool.callforAskUserQuestionorExitPlanMode, a question or a plan. Here the wait is wrapped around the call itself:startWaitingbeforenext(e), andstopWaiting()in afinally, so it ends when the tool returns however it returns.turn.completewith a question in the desktop app’s next-step box, a turn that ended by asking you something.
What ends it
No timer is set, so there is nothing to cancel. A wait ends when waiting goes back to null, and every sign that you answered does that:
classic.PostToolUseandclassic.PostToolUseFailure: the tool ran, so you allowed it.classic.PermissionDenied: you said no. The comment over these three hooks: “A permission answered, either way: nothing waits any more.”- Any other
tool.call: another step started, so whatever waited was answered. turn.startandturn.complete: a new turn, or the end of this one.
No timer: the heartbeat checks
Narsil already has a heartbeat: $.clock.every(2000, ...) started in session.start, which also counts the cache down (guide 8). On every beat, tickWatch asks one question:
if (waiting && !waiting.isNudged && now - waiting.since >= NUDGE_AFTER_MS) {
waiting.isNudged = true
const text = nudgeText(waiting.what, now - waiting.since)
void announce($, 'question', 'Sigo esperándote', text, say('stillWaiting'), true).catch(
() => undefined,
)
}
The 2.1.325 types offer a one-shot timer, $.clock.after, and a version could start one in each startWaiting and cancel it in each stopWaiting. Narsil does not, and its code says why in another place: a comment in turn.complete notes that a reload of the mod, which follows any turn that edited it, cancels $.clock timers. With the heartbeat, the check is a comparison of two numbers, and none of the places that end a wait has to remember a timer.
The heartbeat does not make the wait survive a reload either: waiting is a module variable and starts empty again. The difference is in how it fails. A lost wait means one missed reminder, never a reminder for something you already answered.
Why once, and why five minutes
isNudged makes it once. A reminder every five minutes would turn Narsil into the kind of alarm people switch off, and the first alert plus one reminder already covers the usual case of a missed notification.
Five minutes is NUDGE_AFTER_MS in hooks/watch.ts. It was two minutes at first; the commit that raised it, 2bcc97c, is titled “calm loop, steps and permission alerts”. The same commit moved the next steps from 3 to 15 minutes: the author was spacing out everything Narsil says unasked.
nudgeText builds the sentence; took from hooks/agents.ts writes the time (“5 min”).
Why it shows even while you look
The last argument to announce, true, is force. The floating window of guide 5 normally appears only when Claude is not in front. A forced event is shown anyway: overlay/server.cjs shows the event when Claude is not in the foreground or the event is forced, and a forced event also reopens a window you closed less than a minute ago.
Neither the code nor the README says why; this guide’s reading is that if five minutes have passed and the thing still waits, the first alert did not work, and the fact that Claude is in front does not mean you saw it.
announce keeps the person’s own choices: muted or quiet means no voice, and the floating window turned off means a system notification instead. Quiet mode (/narsil discreto) silences only the end-of-turn announcements, so a reminder that something needs you still arrives, without the voice.
How it was asked of the AI
The original request for the reminder was not recorded. It arrived on 2026-10-30, before the public task logs.
Recorded: the loop alert that left
The reminder was born in the same commit as a loop alert, which warned when Claude kept failing or editing the same files. The author’s first request in odd/tasks/fleet-view.md in narsil-pet, L1 (2026-11-06, excerpt), removed that one:
“(eliminariamos la alerta de bucle, no la he sentido tan util)”
In English: we would remove the loop alert, I have not found it that useful. The task log turns it into S9, “Loop alert removed”, and commit 21e7288 drops it. The reminder for a waiting permission stayed.
Reconstruction from the commit history
From git log -- hooks/register.tsx hooks/watch.ts:
2027f06(2026-10-30) “fix(alerts): only alert when a permission dialog needs your answer”. The move toclassic.PermissionRequest, which also decides what starts a wait.f7a494e(2026-10-30) “feat: warn about loops, insist on waiting permissions and sum the session up”. The reminder, with a wait of two minutes.2532e7c(2026-11-02) “feat: alert as a question when a turn ends asking in the desktop app’s next-step box”. That question is a wait too today.2bcc97c(2026-11-05) “feat: open the context breakdown from the usage bars and calm loop, steps and permission alerts”. Its message: “a waiting permission is insisted on after 5 minutes”.21e7288(2026-11-06) “refactor: drop the loop alert, the spending count and the open-conversations line”.
A prompt you can use
The following prompt was written for this guide as a suggestion. It is not the author’s prompt.
In my Claude Code mod
my-pet, remind me once when a permission waits too long. Keep a module variablewaitingwithsince,whatandisNudged. Start it inclassic.PermissionRequestafternext(e), unlessresult.decisionis set ore.permission_modeisbypassPermissions. Clear it inclassic.PostToolUse,classic.PostToolUseFailure,classic.PermissionDenied, any othertool.call,turn.startandturn.complete. Do not use$.clock.after: insession.start, start one$.clock.every(2000, ...)heartbeat that, when five minutes have passed andisNudgedis false, sets it and sends one notification with$.ui.notify. Add a test with a mocked clock: nothing at 4 minutes 50 seconds, exactly one reminder after 15 minutes, and none when the permission was answered after one minute.
The minimal code
Written for this guide and checked against the 2.1.325 types (classic.PermissionRequest and its decision, classic.PostToolUse, classic.PostToolUseFailure, classic.PermissionDenied, $.clock.every, $.clock.now, $.ui.notify). It is adapted from hooks/register.tsx and hooks/watch.ts in narsil-pet (GPL-3.0-or-later).
import type { EngineInterface, Register } from 'claude-code'
const NUDGE_AFTER_MS = 5 * 60_000
let waiting: { since: number; what: string; isNudged: boolean } | null = null
async function startWaiting($: EngineInterface, what: string): Promise<void> {
waiting = { since: await $.clock.now(), what, isNudged: false }
}
function stopWaiting(): void {
waiting = null
}
async function beat($: EngineInterface): Promise<void> {
if (!waiting || waiting.isNudged) return
const waited = (await $.clock.now()) - waiting.since
if (waited < NUDGE_AFTER_MS) return
waiting.isNudged = true
const minutes = Math.round(waited / 60_000)
void $.ui
.notify(`Still waiting for you after ${minutes} min: ${waiting.what}`, { title: 'my-pet' })
.catch(() => undefined)
}
export const register: Register = (on) => {
on('session.start', async ($, e, next) => {
$.clock.every(2000, () => void beat($))
return next(e)
})
on('classic.PermissionRequest', async ($, e, next) => {
const result = await next(e)
const isDecided = result.decision !== undefined || e.permission_mode === 'bypassPermissions'
if (!isDecided) await startWaiting($, `permission to use ${e.tool_name}.`)
return result
})
// Answered, either way: nothing waits any more.
on('classic.PostToolUse', async ($, e, next) => {
stopWaiting()
return next(e)
})
on('classic.PostToolUseFailure', async ($, e, next) => {
stopWaiting()
return next(e)
})
on('classic.PermissionDenied', async ($, e, next) => {
stopWaiting()
return next(e)
})
// A subagent's turns are not this conversation's: they leave the wait alone.
on('turn.start', async ($, e, next) => {
if (e.agentId === undefined) stopWaiting()
return next(e)
})
on('turn.complete', async ($, e, next) => {
if (e.agentId === undefined) stopWaiting()
return next(e)
})
}
Narsil also clears the wait in its tool.call hook, where another step starting means the wait was answered, and starts one for AskUserQuestion and ExitPlanMode there. The first guide shows a version of that hook.
Common mistakes and how to test it
- Starting a wait for asks nobody sees. Under bypass permissions, or when a settings hook answers, no dialog appears. Check
result.decisionande.permission_modeafternext(e). - Forgetting one way out. A wait that is never cleared reminds you of something you answered long ago. List every path: allowed, failed, denied, another step, a new turn.
- Insisting forever. Without the
isNudgedflag, the heartbeat reminds you every two seconds after the fifth minute. - Relying on a timer across a reload.
$.clocktimers die with a reload of the mod. A heartbeat that compares times is easier to reason about. - Blocking the heartbeat. The reminder is sent with
void … .catch(...): a slow notification must not hold up the beat that also counts the cache.
To test, claude plugin test . runs tests/narsil.test.tsx with a mocked clock. “a permission left waiting five minutes is insisted on once, even while you look” raises a classic.PermissionRequest, finds no reminder at 4 minutes 50 seconds, then exactly one after ten more minutes, of kind question, with force set and the text “Sigo esperándote desde hace 5 min: pido permiso para usar Bash.”. “a permission or question answered in time is not insisted on” answers after a minute and expects none.
Going further
tickWatchinhooks/register.tsxalso sums the session up after 30 quiet minutes (IDLE_SUMMARY_MSandsummaryTextinhooks/watch.ts), shown like a tip.announceQuestionraises the first alert for the same three cases, andsetMood($, 'asking', ...)puts the band in “TE NECESITA”.- The hub of guide 3 ranks a conversation that waits above one that works, so the reminder and the list agree on what matters.
Going further: how the real mod does it
These files are part of the original mods, published under the GPL v3. Code quoted on this page comes from them and keeps that license.
Did this guide help?
Every guide is free. If this one saved you time, you can buy me a coffee.
Buy me a coffee