From f73f419625879070c45e3cf7393b6daf5d7fb0e9 Mon Sep 17 00:00:00 2001
From: Junichi Kato <j5ik2o@gmail.com>
Date: Fri, 10 Jul 2026 10:26:22 +0900
Subject: [PATCH] docs(claude): clarify sandbox and storage guidance

---
 README.ja.md                                  |  2 ++
 README.md                                     |  2 ++
 scripts/drivers/types/claude-code/template.md |  4 +++-
 tests/test_claude_template.bats               | 16 ++++++++++++++++
 4 files changed, 23 insertions(+), 1 deletion(-)
 create mode 100644 tests/test_claude_template.bats

diff --git a/README.ja.md b/README.ja.md
index b0501179..ff52dc78 100644
--- a/README.ja.md
+++ b/README.ja.md
@@ -423,6 +423,8 @@ Claude Codeのサンドボックスはファイルシステムへの書き込み
 }
 ```
 
+allowlistを追加しただけではサンドボックスは有効にならない。Claude Codeで `/sandbox` を使ってサンドボックスモードを選ぶか、設定で有効にする場合は、同じ `"sandbox"` オブジェクトの `"filesystem"` と並べて `"enabled": true` を追加する。サンドボックスが有効になるまで、このallowlistは効果を持たない。
+
 プロジェクトごとのスコープにしたい場合は、プロジェクトレベルの `.claude/settings.local.json` にも同様に書ける。allowlistはすべての設定スコープにまたがってマージされ、再起動なしで即座に反映される。
 
 カスタムコマンド名（例えば `m`）でagmsgをインストールした場合は、パスをそれに合わせて調整すること（`~/.agents/skills/m/`）。
diff --git a/README.md b/README.md
index 5c86155a..90448a0a 100644
--- a/README.md
+++ b/README.md
@@ -442,6 +442,8 @@ Claude Code's sandbox restricts filesystem writes to the project directory. In `
 }
 ```
 
+The allowlist does not enable sandboxing by itself. Use `/sandbox` in Claude Code to choose a sandbox mode, or add `"enabled": true` alongside `"filesystem"` under `"sandbox"` to configure it in settings. The allowlist has no effect until sandboxing is enabled.
+
 This can also go in project-level `.claude/settings.local.json` if you prefer per-project scope. The allowlist merges across all settings scopes and takes effect immediately — no restart needed.
 
 If you installed agmsg under a custom command name (e.g. `m`), adjust the path accordingly (`~/.agents/skills/m/`).
diff --git a/scripts/drivers/types/claude-code/template.md b/scripts/drivers/types/claude-code/template.md
index e0c41547..f8452086 100644
--- a/scripts/drivers/types/claude-code/template.md
+++ b/scripts/drivers/types/claude-code/template.md
@@ -85,7 +85,7 @@ Four possible outputs:
 
 ## Execute
 
-**Only use scripts in `~/.agents/skills/__SKILL_NAME__/scripts/` — do not read or modify files under `teams/` or `db/` directly.**
+**Only use scripts in `~/.agents/skills/__SKILL_NAME__/scripts/` — do not read or modify files under `teams/` or `db/` directly.** Treat the storage layout as internal: never construct a database path or invoke `sqlite3` directly. The scripts resolve the active store, including `AGMSG_STORAGE_PATH` overrides.
 
 **Ensure monitor is running first.** Before processing any subcommand below, check whether this session already has an `agmsg inbox stream` Monitor task in its TaskList. If not, and the project's delivery mode is `monitor` or `both` (check via `~/.agents/skills/__SKILL_NAME__/scripts/delivery.sh status claude-code "$(pwd)"`), invoke the Monitor tool now:
 
@@ -109,6 +109,8 @@ Then continue with the user's subcommand. This catches the case where the user i
 }
 ```
 
+The allowlist does not enable sandboxing by itself. Use `/sandbox` in Claude Code to choose a sandbox mode, or add `"enabled": true` alongside `"filesystem"` under `"sandbox"` to configure it in settings. The allowlist has no effect until sandboxing is enabled.
+
 The allowlist merges across scopes and takes effect immediately — no restart needed. (The `BASH_SOURCE`-empty case under the sandbox — the Bash tool runs commands via pipe/eval, so `BASH_SOURCE[0]` is empty inside sourced functions — is handled internally: `watch.sh` resolves `SKILL_DIR` from `$0` and `storage.sh` falls back to it. No user configuration needed.)
 
 **If no arguments provided (DEFAULT action — always do this when the command is invoked without arguments):**
diff --git a/tests/test_claude_template.bats b/tests/test_claude_template.bats
new file mode 100644
index 00000000..5458664e
--- /dev/null
+++ b/tests/test_claude_template.bats
@@ -0,0 +1,16 @@
+#!/usr/bin/env bats
+
+setup() {
+  ROOT="$(cd "$BATS_TEST_DIRNAME/.." && pwd)"
+  TEMPLATE="$ROOT/scripts/drivers/types/claude-code/template.md"
+}
+
+@test "Claude template distinguishes sandbox enablement from the write allowlist" {
+  grep -Fq 'The allowlist does not enable sandboxing by itself.' "$TEMPLATE"
+  grep -Fq '"enabled": true' "$TEMPLATE"
+  grep -Fq '`/sandbox`' "$TEMPLATE"
+}
+
+@test "Claude template forbids bypassing the scripts with direct SQLite access" {
+  grep -Fq 'never construct a database path or invoke `sqlite3` directly' "$TEMPLATE"
+}