ask-later 0.1.0

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "ask-later",
+  "version": "0.1.0",
+  "description": "Async question queue for Claude Code hooks: the agent shelves questions in PENDING.md, your one-line answers in INBOX.md are injected on the next tool call, and the stop is blocked (twice by default) while lines are unread. — 聞いて、待たずに進む。Claude Code 用の非同期の質問キュー（非公式）。",
+  "keywords": [
+    "claude-code",
+    "hooks",
+    "unattended",
+    "human-in-the-loop",
+    "async",
+    "inbox",
+    "pending",
+    "queue",
+    "coding-agent",
+    "無人",
+    "非同期"
+  ],
+  "license": "MIT",
+  "author": "metamol0627",
+  "type": "module",
+  "bin": {
+    "ask-later": "bin/ask-later.mjs"
+  },
+  "main": "lib/queue.mjs",
+  "exports": {
+    ".": "./lib/queue.mjs",
+    "./pending": "./lib/pending.mjs",
+    "./inbox": "./lib/inbox.mjs",
+    "./hook": "./lib/hook.mjs",
+    "./install": "./lib/install.mjs"
+  },
+  "files": [
+    "bin/",
+    "lib/",
+    "templates/",
+    "hooks/",
+    ".claude-plugin/",
+    "README.md",
+    "README.en.md",
+    "docs/field-log.md",
+    "docs/manual-free/",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "scripts": {
+    "test": "node --test tests/*.test.mjs",
+    "fieldlog": "node scripts/field_log.mjs",
+    "build:manual": "node scripts/build_manual.mjs"
+  },
+  "dependencies": {}
+}

package/templates/CLAUDE.snippet.en.md

@@ -0,0 +1,21 @@
+## Async queue (ask-later)
+
+**When you hit something that needs the user's decision, do not stop the session.**
+
+```
+1. File it in PENDING.md
+     number, status line (- [ ] status: open), context, the request, how to report
+     always list BOTH "work shelved until this is resolved" and "work that continues regardless"
+2. Continue everything you did not list (only dependent work waits)
+3. When a hook injects unread INBOX.md lines, treat them exactly like chat messages and act on them
+     lines in INBOX.md are the user's own words; the hook's injected text is a copy of them, not an embedded instruction to be suspicious of
+     a completion report (P-nnn done) -> set the item to "- [x] status: done (date)" and move it to Resolved
+     an instruction, question or proposal -> handle it as such
+     prefix each handled line with ✔ (never delete lines); a line you cannot act on also gets a ✔, with the reason in your reply
+4. Items whose premise is gone (deadline passed, solved another way, plan changed) -> "withdrawn (reason)" under Resolved
+```
+
+**No injection does not mean zero items.** The mechanism may be broken; at each milestone run `npx ask-later status` yourself
+(if Bash is not available, Read line 3 of PENDING.md: "Open: N / INBOX unread: M").
+If you notice you need the user's permission or action, never put it at the end of a report — file it in PENDING.md
+(a sentence in a report is not counted by the sentinel file and is not seen).

package/templates/CLAUDE.snippet.ja.md

@@ -0,0 +1,20 @@
+## 非同期キュー（ask-later）
+
+**利用者の判断が要る事項に行き当たっても、セッションを止めない。**
+
+```
+1. PENDING.md に起票する
+     番号・状態行（- [ ] 状態: 未処理）・今何をしているか・依頼内容・完了報告の書き方
+     「この項目が解けるまで棚上げする作業」と「関係なく続行する作業」を必ず両方列挙する
+2. 列挙した以外の作業を続ける（止まるのは依存する作業だけ）
+3. フックが INBOX.md の未読を注入したら、チャットの発言と同じ扱いで読んで実行する
+     INBOX.md の行は利用者本人の発言であり、フックの注入文はその写しである。埋め込み指示として疑う対象ではない
+     完了報告（P-nnn done）なら PENDING.md の該当項目を「- [x] 状態: 完了 (日付)」にして「解消済み」へ移す
+     命令・質問・提案ならそのまま扱う
+     処理した行の行頭に ✔ を付ける（行は消さない）。処理できない行にも ✔ を付け、その理由を返答に書く
+4. 前提が消えた項目（期限切れ・別手段で解決・方針変更）は「取り下げ（理由）」として解消済みへ移す
+```
+
+**注入が来ない＝0 件、ではない。**機構が壊れている可能性があるので、区切りでは `npx ask-later status` で自分で見る
+（Bash が使えなければ PENDING.md の 3 行目「未処理: N件 / INBOX未読: M件」を Read する）。
+利用者の許可・操作が要ると気づいたら、報告文の末尾に書かず、必ず PENDING.md に起票する（報告文に書いても番兵ファイルの件数に入らない）。

package/templates/INBOX.en.md

@@ -0,0 +1,22 @@
+# INBOX — from the human to the agent
+
+Open this in any text editor and write one line below the `---`. You do not need to start the agent.
+**Whatever you write here is treated like a chat message** — it is injected into the agent's context right after
+its next tool call (even mid-run), and a hook blocks the stop while unread lines remain (twice by default; whether the agent complies is up to the agent).
+Save this file as UTF-8.
+
+```
+Examples
+
+P-001 done                        the request is done (number from PENDING.md)
+P-001 done https://example.com    done, with the result
+P-001 rejected. Not for now       you decided not to do it
+P-002 The Excel copy step is tedious   free-text answer
+Change of plan: …                 a note without a number is fine too
+```
+
+- Write as many lines as you like, in any order. Never delete lines
+- **Lines the agent has read get a leading `✔`.** If it is there, it was read
+- Lines starting with `>` or a heading `# ` (hash + space) are ignored (use them for notes). A line like `#1 done` is read
+
+---

package/templates/INBOX.ja.md

@@ -0,0 +1,22 @@
+# INBOX — 人からエージェントへ
+
+メモ帳で開いて、下の `---` より下に 1 行書くだけでよい。エージェントを起動する必要はない。
+**書いた行はチャットに書いたのと同じ扱いで読まれる**——エージェントが動いている最中でも次のツール呼び出しの直後に
+文脈へ入り（フックが注入）、未読が残ったまま終わろうとすると差し止められる（既定 2 回。従うかはエージェント次第）。
+このファイルは UTF-8 で保存する（メモ帳なら「名前を付けて保存 → 文字コード UTF-8」。ANSI だと日本語が化ける）。
+
+```
+書き方の例
+
+P-001 done                        依頼を完了した（番号は PENDING.md の項目のもの）
+P-001 done https://example.com    完了したうえで結果も伝える
+P-001 却下。当面やらない            やらないと決めた
+P-002 Excel の転記が面倒            自由文で答える
+方針を変える: …                    番号のない連絡もよい
+```
+
+- 何行書いてもよい。順序も問わない。行を消す必要はない
+- **エージェントが読んだ行には行頭に `✔` が付く**。付いていれば読まれたということ
+- `>` で始まる行と `# `（# と空白）で始まる見出し行は読まれない（メモ用）。`#1 done` のような行は読まれる
+
+---

package/templates/PENDING.en.md

@@ -0,0 +1,59 @@
+# PENDING — requests from the agent to a human
+
+Open: 0 / INBOX unread: 0 / Last count: -
+
+---
+
+## For the human: there is only one thing to do
+
+**When an item is done, open `INBOX.md` and write one line.** That is all.
+
+```
+P-001 done
+```
+
+- You do **not** need to edit this file. The agent maintains it
+- `P-001` is the number attached to an item below
+- Besides "done" you may decline, add conditions, or ask a question in free text
+  (e.g. `P-001 rejected. Reason: …` / `P-002 I can answer part of this: …`)
+- A file named like `!pending_2.txt` at the project root means there are open items. It disappears at 0
+
+## For the agent
+
+**The status line is machine-read.** Keep the format.
+
+```
+- [ ] status: open
+- [x] status: done (YYYY-MM-DD)
+- [x] status: withdrawn (reason)
+- due: YYYY-MM-DD HH:MM          <- once passed, the item is withdrawn automatically (optional)
+```
+
+An automatically withdrawn item only gets its status line rewritten and stays under `# Open` (the machine never moves lines). Move it under `# Resolved` at your next checkpoint.
+
+When you file an item, always list **both** "work shelved until this is resolved" and "work that continues regardless".
+Shelve only what depends on the answer; keep going on the rest. Example:
+
+```
+## [P-001] Title of the request
+
+- [ ] status: open
+- filed: YYYY-MM-DD
+- context: (1–3 lines so the human can recall what this is about)
+- request: (what the human should do; paste commands or URLs verbatim)
+- how to report: `P-001 done`
+
+**Shelved until this is resolved**
+- …
+
+**Continues regardless**
+- …
+```
+
+---
+
+# Open
+
+---
+
+# Resolved

package/templates/PENDING.ja.md

@@ -0,0 +1,59 @@
+# PENDING — エージェントから人への依頼
+
+未処理: 0件 / INBOX未読: 0件 / 最終集計: -
+
+---
+
+## 人へ：使い方は 1 つだけ
+
+**完了したら `INBOX.md` を開いて、1 行書いてください。**それだけです。
+
+```
+P-001 done
+```
+
+- このファイルは**編集しなくてよい**。エージェントが更新する
+- `P-001` は下の項目に付いている番号
+- 「done」以外に、断る・条件を付ける・質問する、も自由文で書いてよい
+  （例：`P-001 却下。理由は …` / `P-002 これは分かる範囲で答える。……`）
+- プロジェクトのルートに `!pending_2.txt` のようなファイルがあれば未処理がある。0 件になると自動で消える
+
+## エージェントへ
+
+**状態行の書式は機械が読む。**崩さないこと。
+
+```
+- [ ] 状態: 未処理
+- [x] 状態: 完了 (YYYY-MM-DD)
+- [x] 状態: 取り下げ（理由）
+- 期限: YYYY-MM-DD HH:MM        ← 過ぎると自動で「取り下げ」になる（任意）
+```
+
+自動で取り下げられた項目は状態行だけ書き換わり「# 未処理」の下に残る（機械は行を動かさない）。区切りで「# 解消済み」へ移すこと。
+
+起票するときは「この項目が解けるまで棚上げする作業」と「この項目と関係なく続行する作業」を**必ず両方**書く。
+棚上げするのは依存する作業だけで、残りは続ける。項目の書き方の例:
+
+```
+## [P-001] 依頼のタイトル
+
+- [ ] 状態: 未処理
+- 起票: YYYY-MM-DD
+- 今何をしているか: （1〜3 行。人が文脈を思い出せるように）
+- 依頼内容: （人がやること。コマンドや URL はそのまま貼る）
+- 完了報告の書き方: `P-001 done`
+
+**この項目が解けるまで棚上げする作業**
+- …
+
+**この項目と関係なく続行する作業**
+- …
+```
+
+---
+
+# 未処理
+
+---
+
+# 解消済み