DEV Community: Agent Island Pro

How to know when Claude Code is done

Agent Island Pro — Wed, 09 Sep 2026 02:23:04 +0000

You start a long task, switch to something else, and come back nine minutes later to find it finished eight minutes ago — or worse, that it stopped to ask you a question and has been sitting there since.

There is a built-in notification for this. It is off in most terminals, and it only fires when Claude Code believes you are away.

Settings below are from Claude Code's own documentation, September 2026.

The part that is already built in

Claude Code fires a notification when it finishes a task or pauses for a permission prompt — with a condition that explains most of the "it never notifies me" reports: it only fires when you appear to be away from the terminal.

If you are sitting in the window watching it work, there is nothing to interrupt you about, so nothing happens. Testing it by staring at the terminal is therefore a test designed to fail.

The second condition is the terminal itself. A desktop notification is sent by default in Ghostty, Kitty and iTerm2, and nowhere else. In any other terminal — Warp, the VS Code integrated terminal, Apple Terminal, Alacritty — nothing arrives until you ask for the bell instead:

// ~/.claude/settings.json
{
  "preferredNotifChannel": "terminal_bell"
}

Three further things swallow the notification even once it is enabled, and each looks like the feature being broken:

If	Then
You use iTerm2	Forwarding is not on by default. Settings → Profiles → Terminal, enable Notification Center alerts, then under Filter Alerts allow escape-sequence-generated ones.
You run inside tmux	tmux swallows it. `set -g allow-passthrough on` in `~/.tmux.conf`, then `tmux source-file ~/.tmux.conf`.
Nothing appears anywhere	Check the terminal application itself has notification permission in your OS settings — the notification is delivered by the terminal, not by Claude Code.

If you would rather have a sound you choose, a Notification hook runs alongside the built-in one rather than replacing it:

{
  "hooks": {
    "Notification": [
      { "hooks": [{ "type": "command",
                    "command": "afplay /System/Library/Sounds/Glass.aiff" }] }
    ]
  }
}

That is the whole of the built-in answer, and for a single session it is usually enough. The rest of this is about why it stops being enough, and it starts with a definition problem.

"Done" is three states, not one

If you build anything on top of this — a notifier, a status line, a dashboard — the first thing you discover is that "is it done?" has no single answer. There are three states, they mean different things to you, and only one is urgent:

State	What it means	Does it need you?
Running	Working. Tools are being called.	No
Waiting	Stopped mid-task on a permission prompt, a question, or a plan to approve.	Yes, and it is blocked until you answer
Idle	The turn ended. It said its piece and is waiting for your next instruction.	Only when you want it to

The events map onto those states cleanly enough once you know which is which:

UserPromptSubmit and PostToolUse → running. Each is also proof of life, which matters later.
Notification → waiting. The message says whether it is a permission request or a question.
Stop → idle. Not "the work is finished" — it means this turn ended, which is a much smaller claim.
SubagentStop → nothing, as far as the parent is concerned. A subagent finishing says nothing about whether the session that spawned it needs you.

The distinction that matters most is Waiting versus Idle, because they feel identical from the outside — in both cases the terminal has gone quiet — and they could not be more different. Idle means you can look whenever you like. Waiting means it stopped mid-task and nothing will happen until you answer, which is the case where a nine-minute delay is nine minutes wasted.

A notifier that treats "quiet" as one state will either nag you about every finished turn or let you sit on a blocked prompt.

The trap: a status nobody is going to correct

Here is the failure I shipped, and it is the one worth stealing the fix for.

On 21 August a session sat showing waiting for your input for over an hour. The user had answered in the terminal within seconds. Nothing was wrong with the answer — the problem was that the hooks had been connected after that session started, so the event that would have cleared the waiting state was never sent. The state was correct when it was written and quietly became a lie afterwards.

This is not a niche case. Any of these produce the same shape:

The session started before your hooks were installed
The process was killed, so no Stop and no SessionEnd ever arrives
The machine slept mid-task
Your hook script broke for ten minutes and you fixed it

An event-driven state machine only knows what it was told. It cannot distinguish "still waiting" from "was waiting, and the update went missing", because both look like silence. So it needs one rule that does not depend on receiving anything:

// After this long with no event at all, a non-idle status
// is no longer evidence of anything.
static let staleAfter: TimeInterval = 10 * 60

func isStale(now: Date) -> Bool {
    status != .idle && now.timeIntervalSince(lastEventAt) >= staleAfter
}

Ten minutes of total silence and we stop asserting the state. Note the status != .idle half: idle is the one state that should persist, because a session that ended its turn an hour ago is still, correctly, a session that ended its turn. Only the active claims expire.

The principle generalises past this codebase: a status you cannot stand behind must not be presented as current, and stale evidence should decay on its own rather than wait for a correction that may never come.

Two hooks, opposite designs

One last thing worth copying if you write your own. Status events and permission prompts want opposite designs, and using one design for both is how you end up with a notifier that makes your agent feel slow.

	Status events	Permission prompt
Job	Report what happened	Answer a question, or decline to
Design	Fire and forget	Blocking
My timeout	`curl -m 0.3`	`curl -m 52`, inside a configured `"timeout": 55`
On failure	Give up silently, exit 0	Print `{}` — no opinion — and exit 0 (exit 2 would block)

A status hook must never make the CLI wait: nothing depends on its answer, so a third of a second is generous and anything longer is a tax on every single tool call.

A permission hook is the opposite — something is waiting on its answer — but it still has to return inside whatever timeout it was given. The default for a command hook is 600 seconds, which is much longer than you want a blocking hook to hold a tool call, so set it deliberately.

Both exit 0 on an ordinary failure, and deliberately so, because exit 2 would block the call. There is more on that in why your Claude Code hook isn't running.

Originally published at agentislandapp.github.io/done.html. I write these while building AgentIsland, a macOS app that puts this state in the notch: a dot per session while things are running, and the actual permission prompt the moment one is waiting.

Why your Claude Code hook isn't running

Agent Island Pro — Mon, 07 Sep 2026 22:07:53 +0000

A hook that fails does not announce it. It just never seems to fire, and you are left guessing whether the problem is your script, your matcher, or your JSON.

There is a flag that answers that in one line, and then five failure modes that account for nearly all of the rest.

Flags checked against the CLI directly; behaviour against the hooks documentation, September 2026. Where a number below comes from my own config rather than a default, it says so — an earlier version of this post did not, and got the timeout wrong as a result.

First: find out whether it ran at all

Almost every hook debugging session starts in the wrong place — reading the script — when the actual question is whether Claude Code ever invoked it. Ask directly:

claude --debug hooks

--debug takes an optional category filter, so this starts a normal session with hook activity logged and the rest of the noise left out. You will see which hooks are considered for each tool call and which are actually executed.

That single line splits the problem in half: if your hook never appears, the fault is in your configuration and nothing in your script can fix it. If it appears and runs, the fault is in what it printed or how long it took.

Two companions worth knowing:

claude --debug-file /tmp/cc.log writes the debug log to a file instead of into your session, which is much easier to read after the fact than a scrolled-away terminal. It enables debug mode on its own, so you do not need both flags.
claude --bare starts a session that skips hooks entirely (along with LSP and plugins). This is the isolation test: if the misbehaviour you are chasing also happens under --bare, your hook was never the cause.

What the configuration actually looks like

Hooks live in settings.json under a hooks key, and the shape is three levels deep, which is where a lot of hand-written config goes wrong. Event name, then a list of matcher groups, then a list of hooks in each group:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash|Write|Edit|NotebookEdit|WebFetch",
        "hooks": [
          {
            "type": "command",
            "command": "\"/Users/you/Library/Application Support/YourApp/hook.sh\"",
            "timeout": 10
          }
        ]
      }
    ]
  }
}

That is a real installed hook, reformatted only for width. The events you can hang a hook on are PreToolUse, PostToolUse, Notification, UserPromptSubmit, Stop, SubagentStop, PreCompact, SessionStart and SessionEnd.

The matcher is optional, and omitting it is usually what you want for the non-tool events. A group with no matcher key fires for every occurrence of that event.

The five things that silently stop a hook

1. A path with a space in it, unquoted

The most common one on macOS, and entirely self-inflicted, because the natural place to put a helper script is ~/Library/Application Support/… — a path with a space in the middle of it. The command string is handed to a shell, so an unquoted path splits into two arguments and the shell reports a file that does not exist, to nobody.

❌  /Users/you/Library/Application Support/YourApp/hook.sh
✅  "/Users/you/Library/Application Support/YourApp/hook.sh"

Inside JSON those quotes have to be escaped, which is how you end up with the \" soup in the example above. It looks wrong and it is correct.

2. A matcher that does not match

The matcher is tested against the tool name, so it has to be the name Claude Code uses — Bash, Write, Edit, NotebookEdit, WebFetch — not the command you are running and not a lowercase version.

A matcher of bash will not match Bash. A matcher of npm will never match anything, because no tool is called that; the command is input to the Bash tool, not a tool of its own. If --debug hooks shows your hook being considered but never run, this is almost always why.

3. Misreading what the exit code does

A hook has two channels, and conflating them causes trouble in both directions.

What it prints on stdout can carry a decision — for a PreToolUse hook, JSON becomes the decision, and printing {} means no opinion, so the normal permission flow happens exactly as if the hook were not installed.

But the exit code is not merely advisory:

Exit 2 blocks, and it wins. On events that can block, exit 2 stops the tool call whether or not you printed JSON — it overrides even a JSON permissionDecision of allow, and it stops the call before permission rules are evaluated, so it beats an allow rule too.

That makes it a deliberate tool, and also a hazard: a script that dies with status 2 for an unrelated reason blocks real work.

So the rule is not "never exit non-zero" — it is that an ordinary failure must exit 0. Reserve a non-zero status for a block you actually mean.

Fail open, never closed. If your hook cannot reach whatever it consults, exit 0 and let the normal flow happen. A hook that fails closed converts one bug in a shell script into a session that cannot run anything, and the failure looks like the agent being broken, not like your hook being broken.

4. The timeout you did not set

The default for a command hook is 600 seconds on most events — lower on a few, such as 30 for UserPromptSubmit and 10 for MessageDisplay.

Ten minutes is far longer than you want a blocking hook to hold a tool call, so set timeout explicitly in the config rather than inheriting it. Then give the work inside the script a slightly shorter deadline than the timeout you set, so it always answers rather than being killed mid-thought.

Mine waits on a person clicking a button: "timeout": 55 in the config, curl -m 52 in the script, three seconds of headroom. Those are my numbers, not defaults.

5. A PATH that is not your shell's

Your hook is not launched from your interactive shell, so it does not inherit what your shell profile sets up. A hook that calls jq, node, uv or anything else installed by a version manager can work perfectly when you run it by hand and find nothing when Claude Code runs it.

Use absolute paths for interpreters and helpers, or resolve them explicitly at the top of the script. This is the failure mode that most reliably survives an afternoon of debugging, because every manual test of the script passes.

A checklist, in the order that finds it fastest

Check	What it rules out
`claude --debug hooks`	Config problem or script problem — do this first, always
`ls -l` the script	Not executable. It needs the executable bit and a shebang
Run it by hand, echoing its output	Invalid JSON, or output on stderr instead of stdout
Quote the path in `command`	The space in `Application Support`
Compare the matcher to the real tool name	Case, and matching the command instead of the tool
`claude --bare`	Whether your hook was ever involved in the symptom at all

One thing a hook is not

Hooks and permission rules are separate gates, and a hook does not override the rules: Claude Code evaluates deny and ask regardless of what the hook returned. A matching deny still blocks and a matching ask still prompts, even if the hook said allow.

The ordering of those gates, and why an allow rule stops applying the moment one part of a chained command is not covered, is a separate piece.

Originally published at agentislandapp.github.io/hooks.html. I write these while building AgentIsland, a macOS app that installs exactly the hooks described above and puts Claude Code's permission prompts in the notch.

Why your Claude Code allow rules keep asking anyway

Agent Island Pro — Mon, 07 Sep 2026 11:39:00 +0000

Correction, 7 September 2026. The first version of this post claimed an allow rule is a prefix match against the whole command string, and that cd frontend && npm test therefore fails because the string starts with cd. That is wrong. Claude Code is aware of shell operators and checks each subcommand independently. I had verified the behaviour against my own app's matcher and written it up as though it were Claude Code's — which is exactly the mistake this post now warns about. Corrected throughout, and the real explanation is more useful than the wrong one was. Sources linked below.

You allowed npm test. It is still asking.

The reason is almost never the rule you wrote. It is that Claude Code splits a compound command and every subcommand has to match a rule of its own — and that several shapes of command can never be auto-approved by a prefix rule at all.

Checked against Claude Code's permissions and hooks documentation, September 2026.

The order the rules are evaluated in

There are three kinds of permission rule, not two, and the third is the one people forget they set. They are evaluated in a fixed order and the first match wins:

Rule	Effect
deny	Blocks the call.
ask	Prompts you, even in modes where nothing would otherwise prompt.
allow	Runs with no prompt.

Specificity does not change that order, which produces two results worth internalising:

A broad deny cannot carry exceptions. Bash(aws *) in deny blocks aws s3 ls even if you also allow exactly that. If you need exceptions, do not write the deny.

An ask rule beats your allow rule. If something still prompts and you cannot see why, look for an ask entry before you touch the allow list. A matching ask prompts even when a more specific allow rule also matches.

Each subcommand is matched on its own

This is the actual answer to the question in the title. Claude Code recognises &&, ||, ;, |, |&, & and newlines as command separators, splits on them, and requires that every resulting subcommand match a rule. A chain is allowed only if all of its parts are.

cd packages/api && ls        ✅ cd into your working directory is read-only,
                              and ls qualifies on its own

cd packages/api && npm test  ✅ with Bash(npm test *) — the cd half is
                              read-only, the npm half matches your rule

git status && npm publish    ❌ npm publish is not covered by anything,
                              so the whole chain prompts

One uncovered part is enough to make the whole line prompt. That is why adding rules one at a time feels like whack-a-mole: you are covering the part that prompted, and the next chain has a different uncovered part.

The same splitting works in your favour for deny and ask, which apply when any subcommand matches — including one nested in a subshell, a command substitution, or a loop body. An ask rule of Bash(git clean *) still prompts for cd /tmp && git clean -f and for echo "$(git clean -f)".

The pattern syntax, and its three sharp edges

Rule	Matches	Does not match
`Bash(npm test *)`	`npm test`, `npm test --watch`	`npm run build`
`Bash(npm test:*)`	the same thing — `:*` is an equivalent way to write a trailing wildcard
`Bash(ls *)`	`ls`, `ls -la`	`lsof`
`Bash(ls*)`	`ls -la` and `lsof`

The space before a trailing * is part of the rule. Bash(ls *) requires a space after ls; Bash(ls*) does not, so it also matches lsof and anything else beginning with those two letters. This is the most common way an allow rule ends up broader than intended.
Put the * after the subcommand. In Bash(git * main) the wildcard stands in for the subcommand itself, so it matches every git subcommand — including -c, which makes git run a program you name. Claude Code warns at startup about a wildcard before the subcommand, and the warning is worth reading rather than dismissing.
:* is only recognised at the end. In Bash(git:* push) the colon is a literal character and the rule matches nothing.

Environment assignments

A leading assignment of a known-safe environment variable is stripped before an allow rule is matched, so Bash(npm test *) does match NODE_ENV=test npm test. An allow rule will not match past an assignment of any other variable. Deny and ask match past any leading assignment, so Bash(rm *) in deny still catches FOO=bar rm -rf tmp/.

Shapes that a prefix rule can never approve

If a command keeps prompting no matter what you add to the allow list, it is probably one of these:

Exec wrappers — watch, setsid, ionice, flock. Bash(watch *) does not auto-approve them, because the wrapper's job is to run something else.
find with -exec or -delete, for the same reason. A Bash(find *) rule does not cover those forms.
An unparseable command. A trailing && with nothing after it, as in npm test &&, cannot be split into subcommands, so even Bash(npm *) will not approve it.

For an exec wrapper you actually want, the only option is an exact-match rule for the full command string.

Where the rules are actually read from

Allow, ask and deny rules are merged from more places than most people expect, and a rule in one file will not show up when you look in another:

~/.claude/settings.json — your own, applies everywhere
<project>/.claude/settings.json — checked into the repo, applies to everyone working on it
<project>/.claude/settings.local.json — yours, for this repo, not checked in
~/.claude.json — the one people miss. Session approvals ("don't ask again") land here under projects → <path> → allowedTools, not in any settings file

That last file explains a specific confusion: you clicked "don't ask again" once, months ago, and now cannot find the rule anywhere in your settings. It is in ~/.claude.json, keyed by the project's absolute path — so it also silently stops applying if you move or rename the directory, or reach it through a different symlink.

Worth knowing what that click actually writes: approving a compound command saves a separate rule for each subcommand that needed approval, up to five, rather than one rule for the whole line. Approving git status && npm test saves a rule for npm test, which is then recognised regardless of what precedes it next time.

Hooks are a separate gate, and they do not override the rules

A PreToolUse hook runs before the permission prompt, and its output can deny the call, force a prompt, or let it through. Two things about it are commonly got backwards — I had one of them backwards myself:

A hook does not bypass deny or ask. Claude Code evaluates those rules regardless of what the hook returned; a matching deny still blocks and a matching ask still prompts, even if the hook said allow.
Exit code 2 blocks, on its own. On events that can block, exit 2 stops the call whether or not you printed JSON — it even overrides a JSON permissionDecision of allow, and it takes precedence over allow rules because it stops the call before the rules are evaluated. So exit status is not merely advisory, and a hook that exits non-zero by accident will block work.

For an ordinary "no opinion" outcome you want exit 0, with either no output or a JSON decision. Fail open, never closed: if your hook cannot reach whatever it consults, exit 0 and let the normal flow happen.

On timeouts, be careful with numbers you read anywhere including here: the default for a command hook is 600 seconds on most events, lower on a few (30 for UserPromptSubmit, 10 for MessageDisplay). A hook that waits on a human should set its own timeout in the config and give its own work a slightly shorter deadline than that. Ours sets "timeout": 55 and uses curl -m 52 inside it — those are our numbers, not Claude Code's defaults.

A worked example: making a destructive command impossible

Deny is evaluated first and applies when any subcommand matches, so this holds in auto mode and inside chains and subshells:

{
  "permissions": {
    "deny": [
      "Bash(sudo date *)",
      "Bash(sudo systemsetup *)",
      "Bash(rm -rf / *)"
    ]
  }
}

Worth knowing the limit of this, because it is easy to over-trust: deny rules constrain the agent's own tool calls. They do not constrain a script the agent wrote and then ran. If the agent writes a Python file that reads your .env and connects to production, that is Python reading a file it is allowed to read, and no rule here sees it. The boundary that holds in that case is what the credential itself is permitted to do — a read-only database user, a reader-role service principal — not what the agent is permitted to type.

Originally published at agentislandapp.github.io/permissions.html. I write these while building AgentIsland, a macOS app that puts Claude Code's permission prompts in the notch so you answer them without hunting for the right terminal window.