Make the monitor mode and delivery.sh set work under Claude Code's sandboxed Bash tool

[tatsuya6502]

Thank you for creating agmsg! This PR fixes two issues that arise when using it with Claude Code's sandbox enabled.

Note that I used LLMs to investigate and fix these issues, as well as writing this PR description. The models I used were the followings:

• GLM-5.1 and GLM-5.2 from Z.ai (for investigation and fixing)
• Claude Opus 4.8 from Anthropic (for testing on a Linux VM)

I used Claude Code as the harness.

All code changes were reviewed and tested by me.

Summary

When Claude Code (CC) runs its Bash tool with the sandbox enabled (macOS sandbox-exec / Seatbelt; Linux seccomp-bpf), two categories of agmsg operations break:

• monitor delivery — watch.sh (launched via the Monitor tool) runs inside the sandbox and can't resolve its DB path, validate a prior watcher, or (without a one-line user config) write its pidfile.
• delivery.sh set <mode> — invoked from a sandboxed Bash tool (e.g. via /agmsg), it aborts before writing settings.local.json.

This PR fixes both, and documents the single required user-side setting.

Why it breaks

Context	Sandboxed?	Scripts that run here
Hooks (SessionStart / Stop / SessionEnd)	No (outside)	session-start.sh, session-end.sh, check-inbox.sh
Monitor tool (persistent bash)	Yes (inside)	watch.sh
Bash tool (ad-hoc, incl. /agmsg)	Yes (inside)	delivery.sh set …, agmsg send …

The sandbox allows reads anywhere, writes only inside an allowlist, and blocks ps. (It also blocks kill -0 for arbitrary PIDs — see Known limitations.) Only the "inside sandbox" rows are affected.

Changes

1. scripts/lib/storage.sh — DB path when BASH_SOURCE[0] is empty

CC's Bash tool runs commands via pipe/eval, so BASH_SOURCE[0] is empty inside sourced functions. agmsg_storage_dir() used it to derive the DB path and fell back to CWD, resolving messages.db under the project dir instead of under the skill.

Fix: add a SKILL_DIR env-var fallback. Every script that sources storage.sh already resolves SKILL_DIR from $0 (which is populated when the script is invoked as a command), so this needs no caller changes. Resolution order is now AGMSG_STORAGE_PATH → BASH_SOURCE[0] → SKILL_DIR → error.

2. scripts/watch.sh — graceful ps fallback

watch.sh validates a prior watcher's cmdline via ps -o args= before killing it (pid-recycling defense, #66). Under the sandbox ps is blocked, which crashed the branch. Now it treats empty ps output as "ps unavailable" and proceeds without the cmdline check.

⚠️ Caveat (see Known limitations): the gate guarding this block is kill -0 "$prev_pid", which is also blocked under the sandbox — so in practice the whole dedup is skipped and a superseded watcher can be orphaned (minor). Documented, not fixed here.

3. scripts/delivery.sh + scripts/release/sync-version.sh — anchor mktemp to $TMPDIR

delivery.sh set … runs under set -euo pipefail. Its settings-injection helpers (strip_agmsg_event_file, add_event_entry_file, prune_empty_hooks_file, apply_settings) each call bare mktemp. On macOS, BSD mktemp with no template resolves the temp dir via confstr(_CS_DARWIN_USER_TEMP_DIR) to /var/folders/.../T/ and ignores the $TMPDIR env var. CC's sandbox blocks that path, so:

$ mktemp
mktemp: mkstemp failed on /var/folders/1j/…/T/tmp.IoANuLvaKm: Operation not permitted

That aborts the entire set before it ever reaches the settings.local.json write. (The hooks file itself is innocent — it lives inside the project and is writable.)

Fix: anchor every mktemp to the sandbox temp dir. GNU mktemp (Linux) already honors $TMPDIR, so the explicit form is portable and strictly safer there too.

tmp=$(mktemp)                                    # before
tmp=$(mktemp "${TMPDIR:-/tmp}/agmsg.XXXXXX")     # after

4. README.md + SKILL.md — document the required allowWrite setting

Monitor mode needs to write pidfiles and SQLite WAL/SHM under ~/.agents/skills/agmsg/, which is outside the project dir. Users with the sandbox enabled must allowlist it. Both docs now describe this and the BASH_SOURCE handling.

User-facing requirement

Users with Claude Code's sandbox enabled need to add (any settings scope):

{
  "sandbox": {
    "filesystem": {
      "allowWrite": ["~/.agents/skills/agmsg/"]
    }
  }
}

Future improvement (not in this PR): delivery.sh set monitor could auto-inject this into .claude/settings.local.json so no manual config is needed.

Testing

Platform	Sandbox	Result
macOS (Apple Silicon)	sandbox-exec (Seatbelt)	✅ monitor delivery end-to-end; delivery.sh set monitor|turn|off all write settings.local.json
Linux VM	seccomp-bpf	✅ monitor delivery verified end-to-end

Known limitations

There are two minor issues remaining under the sandbox.

• delivery.sh status misreports live watchers as dead. do_status classifies pidfiles with kill -0 "$pid", which the sandbox blocks for any pid ≠ $$. A genuinely-running watcher is reported 0 alive, 1 stale. Same mechanism as the ps block; reproduces on macOS and Linux.
• watch.sh prior-watcher dedup is skipped under the sandbox (the kill -0 gate in change Hook UI message semantics (Claude Code and Codex) #2), so a superseded watch.sh can be orphaned until it exits on its own. Minor; the new watcher still takes over via the pidfile.

Both stem from kill -0/ps being unavailable in-sandbox. The right fix is a design choice — a heartbeat file (watch.sh touches run/watch.<sid>.heartbeat each poll cycle; liveness checks read its mtime) is the leading candidate, vs. degrading gracefully ("N pidfiles present, liveness unverifiable"). Left for a follow-up PR because it's a behavior decision best made by the maintainer. Happy to open a separate PR for it.

[fujibee]

Thanks for the thorough writeup and fix, @tatsuya6502 — the sandbox breakdown (hooks run outside, Monitor/Bash-tool run inside) is accurate, and the storage.sh SKILL_DIR fallback plus the mktemp→$TMPDIR anchoring address real failures. Merging this.

One trivial, non-blocking follow-up: in scripts/lib/storage.sh the header comment lists the resolution order as AGMSG_STORAGE_PATH → SKILL_DIR → BASH_SOURCE, but the code checks BASH_SOURCE[0] first and only falls back to SKILL_DIR (if BASH_SOURCE … elif SKILL_DIR). Worth aligning the comment's 2/3 ordering with the code so the documented order isn't inverted.

Heads-up that we tend to merge contributions quickly, so follow-ups are welcome as separate PRs. Thanks again!