claude-task-worker 0.99.0 → 0.101.0

package/README.md

@@ -2,7 +2,7 @@
 
 GitHub Issues/PRを定期ポーリングし、Claude Codeに処理を委譲するCLIツール。
 
-同梱の `claude-task-worker` Claude Code プラグイン（`plugin/`）と組み合わせることで、Issue の実装からPRのレビュー対応、Dependabot PR の対応までを自動化する。CLI 本体（npm パッケージ）とプラグイン（Claude Code マーケットプレイス）は同じリポジトリ・同じ名前で提供される。
+同梱の Claude Code プラグイン（`plugin/`）と組み合わせることで、Issue の実装からPRのレビュー対応、Dependabot PR の対応までを自動化する。CLI 本体（npm パッケージ）とプラグイン（Claude Code マーケットプレイス）は同じリポジトリ・同じ名前で提供される。
 
 ## アーキテクチャ
 
@@ -42,23 +42,10 @@ CLI が GitHub ラベルを検知してタスクを起動し、プラグイン
 共通の挙動:
 
 - 処理中は `cc-in-progress` を付与し、同一 Issue/PR の重複実行を防ぐ
-- `cc-need-human-check` が付いた Issue は全ワーカーの対象外
-- Issue 系ワーカーは `-is:blocked` 検索 qualifier で絞り込むため、未解決の blockedBy を持つ Issue は対象外
+- `cc-need-human-check` が付いた Issue、未解決の blockedBy を持つ Issue は対象外
 - 完了時にトリガーラベルを除去し、次のワーカーへ引き継ぐラベルを付与する
-- `create-ui-design` / `apply-ui-design` は `uiDesign.enabled` が `true` のときだけ起動する（既定 `false`）
-- 定期ワーカー3つ（`update-coding-guidelines` / `update-requirement-rules` / `update-design-md`）はラベルではなく時刻を条件に24時間おきに1回動く。表の「間隔」は24時間経過したかを確認する頻度
-- `update-design-md` は `uiDesign.enabled` が `true` のときだけ起動する
-
-### プラグインの構成
-
-| ディレクトリ | 内容 |
-|---|---|
-| `plugin/skills/` | ワーカーが呼ぶスキル群と、対話セッション用の補助スキル（`commit-push` / `create-pr` / `breakdown-issues` / `edit-pencil-design` など） |
-| `plugin/agents/` | サブエージェント定義（`explore-agent` / `frontend-implementer` / `general-purpose-assistant` / `lightweight-assistant` / `pencil-design-updater` / `requirement-todo-organizer`） |
-| `plugin/hooks/` | `SessionStart`（worktree セットアップ / `git fetch --prune`）と `UserPromptSubmit`（`codegraph prompt-hook`）のフック定義 |
-| `plugin/scripts/` | フック・スキルから呼ばれるスクリプト（`setup-worktree.sh` / `stop-servers.mjs` / `resolve-pr-comments.sh` — `resolve-pr-comments` スキルが GitHub MCP を使えない場合の `gh` フォールバック） |
-| `plugin/references/` | 複数スキルが共有する参照ドキュメント（GitHub アクセス方針など） |
-| `plugin/.mcp.json` | MCP サーバー定義（`codegraph` / `context7` / `next-devtools` / `shadcn` / `playwright`） |
+- 定期ワーカー3つ（`update-*`）はラベルではなく時刻を条件に24時間おきに1回動く。表の「間隔」は24時間経過したかを確認する頻度
+- UIデザイン系3ワーカー（`create-ui-design` / `apply-ui-design` / `update-design-md`）は `uiDesign.enabled` が `true` のときだけ起動する（既定 `false`）
 
 ## セットアップ
 
@@ -69,16 +56,15 @@ CLI が GitHub ラベルを検知してタスクを起動し、プラグイン
 | [Node.js](https://nodejs.org/) >= 22.6.0 | CLI の実行ランタイム |
 | [GitHub CLI (`gh`)](https://cli.github.com/) | 全 GitHub 操作（認証済みであること） |
 | [Claude Code (`claude`)](https://docs.anthropic.com/en/docs/claude-code) | タスク実行エンジン |
-| [Git](https://git-scm.com/) | worktree の作成・ブランチ操作 |
-| [jq](https://jqlang.org/) | プラグインスキル内での JSON 加工 |
-| [CodeGraph](https://www.npmjs.com/package/@colbymchenry/codegraph) | コード探索用インデックス。任意（未導入でも探索がテキスト検索に落ちるだけ） |
-| [Pen CLI](https://docs.pen.dev/for-developers/pen-cli) | `.pen` デザインファイルの編集・参照。UIデザイン先行ワークフロー使用時のみ（要ログイン。呼び出しは `pencil` 経由） |
-| [Playwright](https://playwright.dev/) のブラウザ（chromium） | Playwright MCP でのブラウザ確認。`install` / `update` が取得する（バイナリのみ。CLI のグローバル導入はしない）。Linux ではシステムライブラリ（`install-deps`）も併せて導入する（非 root では `sudo` 経由なのでパスワードを求められることがある） |
-| [DESIGN.md CLI](https://github.com/google-labs-code/design.md) | `DESIGN.md` の lint。`update-design-md` 使用時のみ（呼び出しは `designmd` 経由。未導入でもスキルは動く） |
-| [herdr](https://herdr.dev) | `--project` / `mode: "herdr"` 使用時のみ |
-| [GitHub MCP](https://github.com/github/github-mcp-server) | GitHub アクセスの高速化・クラウド実行時のプロキシ制限回避。Claude 側のコネクタで有効化する（任意。未設定でも `gh` へフォールバックする） |
+| [Git](https://git-scm.com/) / [jq](https://jqlang.org/) | worktree 操作 / スキル内での JSON 加工 |
+| [CodeGraph](https://www.npmjs.com/package/@colbymchenry/codegraph) | コード探索用インデックス（任意。未導入ならテキスト検索に落ちる） |
+| [Pen CLI](https://docs.pen.dev/for-developers/pen-cli) | `.pen` の編集・参照。UIデザイン先行ワークフロー使用時のみ（要ログイン） |
+| [Playwright](https://playwright.dev/) のブラウザ | Playwright MCP でのブラウザ確認 |
+| [DESIGN.md CLI](https://github.com/google-labs-code/design.md) | `DESIGN.md` の lint。`update-design-md` 使用時のみ（未導入でも動く） |
+| [herdr](https://herdr.dev) | `--project` / `mode: "herdr"` 使用時のみ（`--cloud` は起動ゲートこそ herdr を要求しないが、実行経路の分岐が未追随のため現状は `mode: "herdr"` が要る） |
+| [GitHub MCP](https://github.com/github/github-mcp-server) | GitHub アクセスの高速化・クラウド実行時のプロキシ制限回避（任意。Claude 側のコネクタで有効化） |
 
-CLI 本体に npm の実行時依存はない（esbuild で `dist/index.js` に単一バンドルされ、Node.js 標準モジュールのみで動作する）。
+CLI 本体に npm の実行時依存はない（Node.js 標準モジュールのみで動作する）。
 
 ### インストール
 
@@ -86,7 +72,7 @@ CLI 本体に npm の実行時依存はない（esbuild で `dist/index.js` に
 npx claude-task-worker install
 ```
 
-マーケットプレイスの追加・プラグインのインストール・CLI 本体のグローバルインストール・CodeGraph CLI / DESIGN.md CLI / Pen CLI のインストール・Playwright ブラウザ（chromium）の取得を一括で行う。いずれかが失敗しても処理は継続し、`[install]` プレフィックス付きでログ出力される（失敗時の終了コードは 1）。インストール後、Claude Code のセッションを再起動するとプラグインが有効になる。
+マーケットプレイス追加・プラグイン導入・CLI 本体のグローバルインストール・各種 CLI（CodeGraph / DESIGN.md / Pen）と Playwright ブラウザの取得を一括で行う。いずれかが失敗しても処理は継続する。インストール後、Claude Code のセッションを再起動するとプラグインが有効になる。
 
 個別にやる場合:
 
@@ -96,38 +82,7 @@ claude plugin marketplace add getty104/claude-task-worker
 claude plugin install claude-task-worker@claude-task-worker
 ```
 
-herdr が必要な場合は `curl -fsSL https://herdr.dev/install.sh | sh` または `brew install herdr`（[ドキュメント](https://herdr.dev/docs/install/)）。
-
-クラウド実行（`--cloud` フラグ）を使う場合は、クラウド VM（Claude Code on the web）側にもプラグイン・CLI が必要になる。claude.ai の環境設定（Environment setup script / セットアップスクリプト欄）に `npx claude-task-worker install` を直接記載しておく。あわせて、クラウドセッションが push / PR 作成を行うには対象リポジトリの GitHub App 連携が必要。
-
-UIデザイン先行ワークフローを使う場合は、同じ claude.ai の環境設定の環境変数欄に `PEN_CLI_KEY` も設定する。`.pen` を扱うスキル（`edit-pencil-design` / `inspect-pencil-node` / `resolve-pencil-conflict`）の Pen CLI 認証に使うもので、クラウド VM では対話ログインができないため。キーの発行元と値の形式は後述の「[Pen CLI のログイン](#pen-cli-のログイン)」を参照。
-
-詳細は後述の「[`--cloud`](#--cloud)」を参照。
-
-### GitHub コネクタの有効化
-
-GitHub MCP は Claude 側のコネクタとして有効化する（本プラグインは `.mcp.json` で宣言しない）。claude.ai の設定 > コネクタ、または Claude Code の `/mcp` から GitHub コネクタを有効化する。
-
-任意の設定であり、未設定でもスキルは `gh` へフォールバックして動作する。対応表は [`plugin/references/github-access.md`](./plugin/references/github-access.md) を参照。
-
-### Pen CLI のログイン
-
-`.pen` を扱うスキル（`edit-pencil-design` / `inspect-pencil-node` / `resolve-pencil-conflict`）は Pen CLI の認証を必要とする。未ログインだと `.pen` の読み書きが失敗するため、UIデザイン先行ワークフローを使うなら**インストール後に一度ログインしておく**。
-
-```bash
-pencil login    # メールアドレス + パスワード、またはメールアドレス + OTP コード
-pencil status   # 認証状態の確認
-```
-
-セッショントークンは `~/.pencil/session-cli.json` に保存され、以降のコマンドで再利用される。
-
-CI やワーカーを実行するマシンなど対話ログインできない環境では、環境変数 `PEN_CLI_KEY`（pen.dev の組織設定 > Developer Keys で発行）を使う。保存済みトークンより優先される。
-
-```bash
-export PEN_CLI_KEY=pencil_cli_...
-```
-
-詳細は [Pen CLI のドキュメント](https://docs.pen.dev/for-developers/pen-cli)を参照。
+herdr は `curl -fsSL https://herdr.dev/install.sh | sh` または `brew install herdr`（[ドキュメント](https://herdr.dev/docs/install/)）。
 
 ### 更新
 
@@ -135,11 +90,11 @@ export PEN_CLI_KEY=pencil_cli_...
 claude-task-worker update
 ```
 
-マーケットプレイス・プラグイン・CLI 本体・CodeGraph CLI / DESIGN.md CLI / Pen CLI をまとめて更新する。プラグインの反映にはセッション再起動が必要。
+マーケットプレイス・プラグイン・CLI 本体・各種 CLI をまとめて更新する。プラグインの反映にはセッション再起動が必要。
 
 ### 初期化
 
-対象リポジトリで実行すると、GitHub ラベル・Issue テンプレート・GitHub Actions ワークフロー・設定ファイルが作成され、CodeGraph のインデックスが構築される。
+対象リポジトリで実行すると、GitHub ラベル・Issue テンプレート・GitHub Actions ワークフロー・設定ファイル（`claude-task-worker.json`）が作成され、CodeGraph のインデックスが構築される。
 
 ```bash
 claude-task-worker init           # 既存ファイルは保護
@@ -151,30 +106,17 @@ claude-task-worker init --force   # 強制上書き
 | ラベル | 用途 |
 |---|---|
 | `cc-triage-scope` | トリアージ対象マーク（Issue/PR） |
-| `cc-issue-created` | `create-issue` 由来の Issue マーク（`triage-created-issue` のトリガー） |
-| `cc-update-issue` | Issue 更新トリガー |
-| `cc-answer-issue-questions` | Issue 確認事項への回答トリガー |
-| `cc-exec-issue` | Issue 実行トリガー |
-| `cc-fix-onetime` | PR 修正トリガー（1回） |
-| `cc-resolve-conflict` | PR コンフリクト解消トリガー |
+| `cc-issue-created` | `create-issue` 由来の Issue マーク |
+| `cc-update-issue` / `cc-answer-issue-questions` / `cc-exec-issue` | Issue の更新 / 確認事項回答 / 実行トリガー |
+| `cc-fix-onetime` / `cc-resolve-conflict` | PR の修正 / コンフリクト解消トリガー |
 | `cc-in-progress` | 処理中ステータス |
-| `cc-need-human-check` | 人間の確認が必要（付与中は Issue ワーカーの対象外） |
+| `cc-need-human-check` | 人間の確認が必要（付与中はワーカーの対象外） |
 | `cc-pr-created` | PR 作成完了マーク |
 | `cc-epic-issue` | エピックマーク（Issue: サブ全 Close で `epic-issue` 起動 / PR: リリースゲート対象） |
-| `cc-release-ready` | エピックPRがリリース可能と判定されたマーク（実際のマージは人間が実施） |
-| `cc-create-ui-design` | UIデザイン作成トリガー |
-| `cc-ui-design-pr-created` | デザインPR作成済み・マージ待ちマーク |
-| `cc-ui-design-ready` | デザイン反映済みマーク（再デザイン抑止） |
-| `cc-ui-design` | デザインPRのマーカー（`triage-pr` のレビュー観点切り替え用） |
-| `cc-cloud-done` | クラウド実行タスクの完了マーク（セッションが最後に付与し、ワーカーが検知して除去する。人が手動で付与しても同じ経路で完了扱いになるため、張り付いたクラウドタスクの救済手段としても使える） |
-
-作成されるファイル:
-
-- `.github/ISSUE_TEMPLATE/cc-triage-scope.yml` — `cc-triage-scope` 付き Issue 作成用テンプレート
-- `.github/workflows/assign-creator-on-cc-triage-scope.yml` — Issue 作成者の自動アサイン
-- `claude-task-worker.json` — 設定ファイル。**ワーカーごとの既定値は書き出さない**（写経するとプラグイン更新で既定が変わっても古い値に固定されるため）。上書きしたいワーカーだけ手で追記する
-
-CodeGraph のセットアップとして、グローバル gitignore（`~/.config/git/ignore`）へ `.codegraph/` を冪等に追記し、`codegraph init` を実行する。CodeGraph 未インストールでも `init` 全体は失敗しない。
+| `cc-release-ready` | エピックPRがリリース可能と判定されたマーク（マージは人間が実施） |
+| `cc-create-ui-design` / `cc-ui-design-pr-created` / `cc-ui-design-ready` | UIデザイン先行ワークフローの各段階 |
+| `cc-ui-design` | デザインPRのマーカー |
+| `cc-cloud-done` | クラウド実行タスクの完了マーク（セッションが付与し、ワーカーが検知して除去する。手動付与で張り付いたタスクを救済できる） |
 
 ## コマンド
 
@@ -184,27 +126,28 @@ claude-task-worker <command> [--epic <issue-number>]... [--label <label>]... [--
 
 | コマンド | 内容 |
 |---|---|
-| 各ワーカー名 | 単一ワーカーを起動（`exec-issue` / `triage-pr` など。上記 Worker 表を参照） |
-| `all` | 通常ワーカー9つ + 定期ワーカー3つの計12ワーカーを同時にポーリング（`triage-created-issue` / `triage-pr` / `check-dependabot` を除く） |
-| `yolo` | 全ワーカーを同時にポーリング（`all` + `triage-created-issue` + `triage-pr` + `check-dependabot`） |
+| 各ワーカー名 | 単一ワーカーを起動（`exec-issue` / `triage-pr` など） |
+| `all` | 通常ワーカー9つ + 定期ワーカー3つ（`triage-created-issue` / `triage-pr` / `check-dependabot` を除く） |
+| `yolo` | 全ワーカーを同時にポーリング |
 | `init` | ラベル・テンプレート・設定ファイルの作成と CodeGraph セットアップ |
 | `install` / `update` | 上記「セットアップ」を参照 |
+| `cloud-setup [--force]` | クラウド VM 側の準備（下記「`--cloud`」を参照） |
 | `usage` | Claude API 使用状況（5時間/7日間の利用率とリセット時刻）を表示し、Slack にも通知 |
 | `version` | CLI のバージョンを表示（`--version` / `-v` も可） |
 
 ### `--epic <issue-number>`
 
-指定したエピック Issue のサブ Issue のみを処理対象に絞る。`all` / `yolo` と Issue 系ワーカーで有効。複数指定するといずれかのエピックを親に持つサブ Issue が対象になる（OR）。
+指定したエピック Issue のサブ Issue のみを処理対象に絞る。複数指定は OR。
 
 ```bash
 claude-task-worker all --epic 100 --epic 200
 ```
 
-`epic-issue` ワーカーだけはエピック Issue 自体が処理対象なので、指定番号は「エピック Issue 自身の番号」として照合される。
+`epic-issue` ワーカーではエピック Issue 自身の番号として照合される。
 
 ### `--label <label>`
 
-トリガーラベルに加えて指定ラベルが付いた Issue のみに絞る。複数指定すると全ラベルの AND。`--epic` と併用可能。ユーザーのスコープ指定なので、タスク完了時にワーカーが除去することはない。
+トリガーラベルに加えて指定ラベルが付いた Issue のみに絞る。複数指定は AND。`--epic` と併用可能。
 
 ```bash
 claude-task-worker all --label priority-high --label needs-design
@@ -212,117 +155,103 @@ claude-task-worker all --label priority-high --label needs-design
 
 ### `--project <name>`
 
-指定したプロジェクト（またはグループ、`all`）へ [herdr](https://herdr.dev) 経由でコマンドをディスパッチする。指定するとCLIはワーカーを直接実行せず、対象プロジェクトごとに独立した herdr ワークスペースを作ってそこでコマンドを実行する。
+指定したプロジェクト（またはグループ、`all`）へ [herdr](https://herdr.dev) 経由でコマンドをディスパッチする。CLI はワーカーを直接実行せず、プロジェクトごとに独立した herdr ワークスペースを作ってそこでコマンドを実行し、稼働状況をステータステーブルに表示する。SIGTERM/SIGINT で全セッションを一括停止する。
 
 ```bash
 claude-task-worker all --project all
-claude-task-worker all --project frontend
-claude-task-worker exec-issue --project app-a --epic 100 --label priority-high
-```
-
-プロジェクト名・グループ名は `$XDG_CONFIG_HOME/claude-task-worker/config.json`（未設定なら `~/.config/claude-task-worker/config.json`）で定義する。`all` は全プロジェクトを指す予約語。
-
-```json
-{
-  "mode": "default",
-  "advisor": false,
-  "permission": "bypassPermissions",
-  "projects": {
-    "app-a": "/Users/me/repos/app-a",
-    "app-b": "/Users/me/repos/app-b"
-  },
-  "projectGroups": {
-    "frontend": ["app-a", "app-b"]
-  }
-}
+claude-task-worker exec-issue --project app-a --epic 100
 ```
 
-ディスパッチャーの機能:
-
-- **一斉起動**: プロジェクトごとに `ctw:<プロジェクト名>` ラベルのワークスペースを作り、そこで（`--project` を除いた）同じコマンドを実行する。ワーカーが実際に起動したかを確認し、起動しなければ再送・失敗判定する
-- **稼働一覧**: プロジェクト名・ワークスペースID・ペインID・ステータス・稼働時間をステータステーブルに描画する
-- **一括停止**: SIGTERM/SIGINT で全セッションへ ctrl-c を送り、終了を待ってワークスペースを閉じる。もう一度送ると強制終了
+プロジェクト名・グループ名は `config.json` で定義する（下記「設定ファイル」）。`all` は全プロジェクトを指す予約語。
 
 `--project` と併用できないコマンド: `init` / `install` / `update` / `usage` / `version`
 
 ### `--cloud`
 
-指定したワーカーのタスクを Claude Code on the web（クラウド VM）で実行する。プロセス単位のフラグで既定は無効。クラウドで実行されるのは `exec-issue` / `fix-review-point` の2つだけで（`CLOUD_ALLOWED_WORKERS`）、それ以外のワーカーは `--cloud` を付けてもローカル実行のまま残る。どのワーカーがクラウドで走るかは起動時に1行ログで示される。
-
-許可リスト方式にしているのは、クラウド実行が「成果ゼロでも完了扱いになり、トリガーラベルの再付与で再起動され続ける」失敗の仕方をするため。`triage-pr` などは GraphQL ゲートで判断材料を取得できず空振りするが、完了扱いになるとポーリング間隔ごとにクラウドセッションを焼き続ける。
+タスクを Claude Code on the web（クラウド VM）で実行する。プロセス単位のフラグで既定は無効。
 
 ```bash
 claude-task-worker exec-issue --cloud
 claude-task-worker all --cloud
 ```
 
+**クラウドで実行されるのは `exec-issue` と `fix-review-point` の2ワーカーだけ**で、それ以外は `--cloud` を付けてもローカル実行のまま残る（`all` / `yolo` にそのまま付けられる）。どのワーカーがクラウドで走るかは起動時にログへ出る。
+
 前提条件:
 
-- `config.json` の `mode` が `"herdr"` であること。新しいクラウドセッションの作成には TTY が必要で、`"default"` の子プロセス実行では作れない。`mode` が `"herdr"` でないのに `--cloud` を付けた場合は**タスクを1件も起動せずエラー終了する**（`"default"` へフォールバックしない）
-- claude.ai アカウントでのサインインが必須。API キー認証（`ANTHROPIC_API_KEY` / `ANTHROPIC_AUTH_TOKEN`）・第三者プロバイダ（Bedrock / Vertex）・カスタムエンドポイント構成では利用できない。この検査（`claude auth status --json` の実行）は `--cloud` を指定したときだけ行う
-- 対象リポジトリの GitHub App 連携（クラウド VM から push / PR 作成を行うため）
-- claude.ai の環境設定のセットアップスクリプト欄に `npx claude-task-worker install` を記載してプラグイン・CLI を導入しておくこと（手順は「[インストール](#インストール)」参照）
-- UIデザイン先行ワークフローを使う場合のみ、claude.ai の環境設定の環境変数欄に `PEN_CLI_KEY`（pen.dev の組織設定 > Developer Keys で発行）を設定しておくこと。`.pen` を扱う3スキルの Pen CLI 認証に使う（「[Pen CLI のログイン](#pen-cli-のログイン)」参照）
+| 前提 | 備考 |
+|---|---|
+| `script` コマンドが使える環境（macOS / Linux） | クラウドセッションの作成には TTY が必要で、それを `script` コマンドの疑似 pty で供給する。platform が darwin/linux でない、または `script` が PATH に無い場合はタスクを1件も起動せずエラー終了する（フォールバックしない） |
+| claude.ai アカウントでのサインイン | API キー認証・第三者プロバイダ（Bedrock / Vertex）構成では利用不可。`--cloud` 指定時のみ検査される |
+| 対象リポジトリの GitHub App 連携 | クラウド VM から push / PR 作成を行うため |
+| claude.ai の「プルリクエストを自動的に作成する」「プルリクエストの自動修正」が **OFF** | 下記 |
+| VM 側のセットアップスクリプト | 下記 |
+| `PEN_CLI_KEY` 環境変数 | UIデザイン先行ワークフローを使う場合のみ（下記「Pen CLI のログイン」） |
+
+claude.ai の設定にある **「プルリクエストを自動的に作成する」「プルリクエストの自動修正」は必ず OFF にする**。どちらもタスクワーカーの制御と競合する。前者はスキルの `create-pr`（`Closes #<N>`・ベースブランチ・ラベル付与）とは別に PR を作るため PR が重複し、後者はセッションが PR 作成後に終了せずレビューを待って修正を続けるため、`cc-cloud-done` による完了検知が 4 時間のタイムアウトまで効かない。
 
-上記のうち静的検査されるのは1〜2番目だけで、GitHub App 連携・クラウド VM 側の導入状況・環境変数の設定はローカルから確認できないため検査されない。
+claude.ai の環境設定（セットアップスクリプト欄）に次の2行を記載しておく。
 
-運用上は次の3ワーカーには `--cloud` を使わないことを推奨する: `fix-review-point` / `triage-pr` / `check-dependabot`。起動自体は許可されるが、クラウドセッションの GitHub プロキシ制限でレビューコメント・CI ステータスなど判断材料を取得できず、タスクが空振りする。ローカルのみで実行したい場合は個別のワーカー名コマンドで `--cloud` を付けずに起動する。
+```bash
+npx claude-task-worker install
+npx claude-task-worker cloud-setup
+```
 
-クラウド実行のタスクは worktree を作らない（クラウド VM が自前でリポジトリを持つため）。
+`cloud-setup` は VM 側の `~/.claude/settings.json` に権限モード・出力スタイル・言語を書き込み、グローバル gitignore へ `.codegraph/` を登録する。クラウドセッションは起動フラグの `--permission-mode` を反映しないため、この設定ファイルが権限モードを指定する唯一の経路になる。書き込みはキー単位のマージで既存の設定を消さない（`--force` で上書き）。
 
-`--project` と併用した場合、`--cloud` は各プロジェクトへそのまま転送される。`--cloud` と併用できないコマンド: `init` / `install` / `update` / `usage` / `version`
+補足:
 
-`claude-task-worker.json` の `workers.<名前>.cloud` 設定は廃止された。設定ファイルに残っている場合は警告ログを出したうえで無視される。
+- クラウド実行のタスクは worktree を作らない（VM が自前でリポジトリを持つため）
+- 完了は `cc-cloud-done` ラベルで検知する。4時間で応答がなければ打ち切り、`cc-need-human-check` を付けて失敗通知する
+- `--project` と併用した場合、`--cloud` は各プロジェクトへそのまま転送される
+- `--cloud` と併用できないコマンド: `init` / `install` / `update` / `usage` / `version`
+- **現時点では `mode: "default"` での `--cloud` はクラウド経路へ流れない**（実行経路の分岐が `mode: "herdr"` 判定のまま未追随のため）。`--cloud` を使うには `mode: "herdr"` にしておく必要がある。追随は別Issueで対応予定
 
 詳細は [`docs/prd-cloud-worker-execution.md`](./docs/prd-cloud-worker-execution.md) を参照。
 
+### Pen CLI のログイン
+
+`.pen` を扱うスキルは Pen CLI の認証を必要とする。UIデザイン先行ワークフローを使うなら一度ログインしておく。
+
+```bash
+pencil login    # メールアドレス + パスワード、またはメールアドレス + OTP コード
+pencil status   # 認証状態の確認
+```
+
+CI やクラウド VM など対話ログインできない環境では、環境変数 `PEN_CLI_KEY`（pen.dev の組織設定 > Developer Keys で発行）を使う。保存済みトークンより優先される。
+
 ## 設定ファイル
 
-グローバル設定は `config.json`（上記）、リポジトリ設定は実行ディレクトリ直下の `claude-task-worker.json`。
+グローバル設定は `$XDG_CONFIG_HOME/claude-task-worker/config.json`（未設定なら `~/.config/claude-task-worker/config.json`）、リポジトリ設定は実行ディレクトリ直下の `claude-task-worker.json`。
 
 ### `config.json`（グローバル）
 
+```json
+{
+  "mode": "default",
+  "advisor": false,
+  "permission": "bypassPermissions",
+  "projects": {
+    "app-a": "/Users/me/repos/app-a",
+    "app-b": "/Users/me/repos/app-b"
+  },
+  "projectGroups": {
+    "frontend": ["app-a", "app-b"]
+  }
+}
+```
+
 | キー | 既定 | 説明 |
 |---|---|---|
 | `projects` | - | プロジェクト名 → 絶対パス |
 | `projectGroups` | `{}` | グループ名 → プロジェクト名配列 |
-| `mode` | `"default"` | タスクの実行形態（下記） |
-| `advisor` | `false` | `--advisor` を渡すか（下記） |
-| `permission` | `"bypassPermissions"` | Claude CLI の権限モード（下記） |
+| `mode` | `"default"` | `"default"`: `claude -p` の子プロセスとして実行 / `"herdr"`: herdr のタブ内で TUI 起動し、実行中の様子を覗ける（`--project` はこちらが必要） |
+| `advisor` | `false` | `true` で `--advisor <model>` を渡す。モデルは `claude-task-worker.json` の `advisorModel` |
+| `permission` | `"bypassPermissions"` | Claude CLI の[権限モード](https://code.claude.com/docs/ja/permission-modes)（`bypassPermissions` / `dontAsk` / `auto` / `acceptEdits` / `manual` / `plan`） |
 
-#### `mode`（タスクの実行形態）
+いずれもトップレベル一括で、プロジェクト単位・ワーカー単位の指定はできない。`permission` はワーカーに承認するユーザーがいないため、`bypassPermissions` / `dontAsk` 以外ではタスクが承認待ちで止まりうる。
 
-全ワーカー・全プロジェクトに一括適用される（個別指定は不可）。
-
-| `mode` | 挙動 |
-|---|---|
-| `"default"` | タスクを `claude -p`（非対話 print モード）の子プロセスとして実行 |
-| `"herdr"` | タスクを herdr のタブ内で TUI セッションとして実行。実行中の様子を herdr で覗ける |
-
-`"herdr"` では、worktree 作成後に `ctw:<プロジェクト名>:#<番号>` ラベルのタブを作り、そのルートペインで claude を TUI 起動する。agent ステータスを監視して完了を検知し、セッション transcript から最終レポートを回収して通知に使う。`blocked`（claude が入力待ち）になっても自動失敗にせず待機し、ステータステーブルに `running:blocked` と表示するので herdr のタブを開いて直接対応できる。herdr が未インストール・未起動なら起動時にエラー終了する（`"default"` へフォールバックしない）。
-
-> ℹ️ タスク完了時の通知音はワーカー側から止められない（音を鳴らすのは herdr サーバープロセスで、`HERDR_DISABLE_SOUND` もそのプロセスの環境変数として読まれるため）。無音にするには `~/.config/herdr/config.toml` に `[ui.sound] enabled = false` を書いて `herdr server reload-config` する。ただし herdr サーバー全体に効くため、対話セッションの完了音も鳴らなくなる。
-
-#### `advisor`（アドバイザーモデル）
-
-`true` にすると、タスク起動時に Claude CLI へ `--advisor <model>` を渡す。渡すモデルは `claude-task-worker.json` の `workers.<名前>.advisorModel`。`mode` と同じくトップレベル一括で、プロジェクト単位・ワーカー単位のオン/オフはできない。空文字が指定されたワーカーには渡さない。
-
-advisor は main モデル以上の能力が必要（Claude CLI の制約）。`model` が `opus` のワーカーに `opus` advisor を付けても意味がなく、既定で `sonnet` のワーカーも `opus` advisor を付けると下げたぶんのコスト削減を打ち消すため、`advisorModel` の既定値は全ワーカー空文字（advisor なし）。`sonnet` のワーカーの品質が落ちた場合の調整弁として `advisorModel: "opus"` を指定できる。
-
-#### `permission`（権限モード）
-
-タスク起動時に Claude CLI へ渡す[権限モード](https://code.claude.com/docs/ja/permission-modes)。`mode` / `advisor` と同じくトップレベル一括で、プロジェクト単位・ワーカー単位の指定はできない。
-
-| `permission` | 挙動 |
-|---|---|
-| `"bypassPermissions"`（既定） | 全許可。承認するユーザーが常駐しない自律実行のため既定 |
-| `"dontAsk"` | 許可されていない操作は確認せずスキップする |
-| `"auto"` | 安全な操作は自動承認、危険な操作のみ確認 |
-| `"acceptEdits"` | ファイル編集は自動承認、それ以外は都度確認 |
-| `"manual"` | 標準の権限確認 |
-| `"plan"` | 読み取りのみ。変更は行わない |
-
-値は Claude CLI の `--permission-mode` にそのまま渡される（choices と同じ綴り）。ワーカーには承認するユーザーがいないため、`bypassPermissions` / `dontAsk` 以外ではタスクが承認待ちで止まりうる（`mode: "herdr"` なら herdr のタブを開いて手動で承認できる）。
+> ℹ️ `mode: "herdr"` の完了通知音はワーカー側から止められない。無音にするには `~/.config/herdr/config.toml` に `[ui.sound] enabled = false` を書いて `herdr server reload-config` する（herdr サーバー全体に効く）。
 
 ### `claude-task-worker.json`（リポジトリ）
 
@@ -331,32 +260,34 @@ advisor は main モデル以上の能力が必要（Claude CLI の制約）。`
 | `fixReviewPointCallbackCommentMessage` | string | - | `fix-review-point` 完了時に PR へ投稿するコメント（未設定なら投稿しない） |
 | `uiDesign` | object | `{ "enabled": false, "designDir": "designs", "yolo": false }` | UIデザイン先行ワークフロー（下記） |
 | `workers` | object | `{}` | ワーカーごとの上書き設定（下記） |
-| `lastRun` | object | `{}` | 定期ワーカーの最終実行時刻（ワーカー名 → ISO8601）。ワーカーが自動更新するため手で編集しない |
+| `lastRun` | object | `{}` | 定期ワーカーの最終実行時刻。ワーカーが自動更新するため手で編集しない |
 
 #### ワーカーごとの設定
 
 未指定のワーカー・フィールドは既定値にフォールバックする。
 
-| フィールド | 型 | 説明 |
-|---|---|---|
-| `skill` | string | Claude CLI の `-p` に渡すスラッシュコマンド。`"<skill> <番号>"` の形で起動される |
-| `model` | string | `--model` の値（`sonnet` / `opus` / `haiku`） |
-| `advisorModel` | string | `--advisor` の値。空文字なら advisor なし。`config.json` の `advisor: true` のときだけ参照される |
-| `effort` | string | `--effort` の値（`high` / `medium` / `low`） |
-| `pollingIntervalSeconds` | number | ポーリング間隔（秒） |
-| `cooldownSeconds` | number | タスク完了後にポーリングを止める時間（秒）。`0` でなし |
-| `maxConcurrentTasks` | number | 同時実行できるタスクの最大数 |
-
-既定値（`skill` は「[Worker とスキルの対応](#worker-とスキルの対応)」を参照。`cooldownSeconds` は `0`、`maxConcurrentTasks` は `1`）:
-
-| ワーカー | `model` | `effort` | `advisorModel` | `pollingIntervalSeconds` |
-|---|---|---|---|---|
-| `exec-issue` / `fix-review-point` / `answer-issue-questions` / `create-issue` / `create-ui-design` / `triage-pr` | `opus` | `high` | `""`（なし） | 60 |
-| `update-issue` / `triage-created-issue` / `resolve-conflict` | `sonnet` | `high` | `""`（なし） | 60 |
-| `check-dependabot` | `sonnet` | `high` | `""`（なし） | 3600 |
-| `epic-issue` / `apply-ui-design` | `sonnet` | `medium` | `""`（なし） | 300 |
-| `update-coding-guidelines` / `update-requirement-rules` / `update-design-md` | `opus` | `high` | `""`（なし） | 3600 |
-| （未知のワーカー名） | `opus` | `high` | `""`（なし） | 60 |
+| フィールド | 説明 |
+|---|---|
+| `skill` | Claude CLI の `-p` に渡すスラッシュコマンド（`"<skill> <番号>"` の形で起動） |
+| `model` | `--model` の値（`sonnet` / `opus` / `haiku`） |
+| `advisorModel` | `--advisor` の値。空文字なら advisor なし。`config.json` の `advisor: true` のときだけ参照される |
+| `effort` | `--effort` の値（`high` / `medium` / `low`） |
+| `pollingIntervalSeconds` | ポーリング間隔（秒） |
+| `cooldownSeconds` | タスク完了後にポーリングを止める時間（秒）。既定 `0` |
+| `maxConcurrentTasks` | 同時実行できるタスクの最大数。既定 `1` |
+
+既定値:
+
+| ワーカー | `model` | `effort` | `pollingIntervalSeconds` |
+|---|---|---|---|
+| `exec-issue` / `fix-review-point` / `answer-issue-questions` / `create-issue` / `create-ui-design` / `triage-pr` | `opus` | `high` | 60 |
+| `update-issue` / `triage-created-issue` / `resolve-conflict` | `sonnet` | `high` | 60 |
+| `epic-issue` / `apply-ui-design` | `sonnet` | `medium` | 300 |
+| `check-dependabot` | `sonnet` | `high` | 3600 |
+| `update-coding-guidelines` / `update-requirement-rules` / `update-design-md` | `opus` | `high` | 3600 |
+| （未知のワーカー名） | `opus` | `high` | 60 |
+
+`advisorModel` の既定は全ワーカー空文字（advisor なし）。
 
 設定例:
 
@@ -365,8 +296,7 @@ advisor は main モデル以上の能力が必要（Claude CLI の制約）。`
   "workers": {
     "exec-issue":       { "model": "opus", "cooldownSeconds": 600, "maxConcurrentTasks": 3 },
     "fix-review-point": { "model": "sonnet", "advisorModel": "opus", "maxConcurrentTasks": 2 },
-    "triage-pr":        { "effort": "medium", "pollingIntervalSeconds": 120 },
-    "check-dependabot": { "model": "haiku", "pollingIntervalSeconds": 7200 }
+    "triage-pr":        { "effort": "medium", "pollingIntervalSeconds": 120 }
   }
 }
 ```
@@ -375,86 +305,58 @@ advisor は main モデル以上の能力が必要（Claude CLI の制約）。`
 
 ### Epic（親Issue）連携
 
-親 Issue（Issue Dependencies の Parent）を持つサブ Issue を処理する場合、ワーカーはデフォルトブランチではなく `cc-epic-<親Issue番号>` ブランチから worktree を作成する。エピック単位でブランチをまとめることで、サブ Issue ごとのPRを単一の統合ブランチへ集約できる。エピックブランチが remote に無ければデフォルトブランチから自動派生して push される。
+親 Issue を持つサブ Issue は、デフォルトブランチではなく `cc-epic-<親Issue番号>` ブランチから worktree を作って処理される。サブ Issue ごとのPRを単一の統合ブランチへ集約するため。エピックブランチが remote に無ければ自動で派生・push される。
 
-サブ Issue がすべて Close されると `epic-issue` ワーカーが `/claude-task-worker:create-epic-pr` を起動し、エピックブランチからまとめてPRを作る。エピックPRは `triage-pr` がマージ可能と判定してもマージせず `cc-release-ready` を付けるだけで、実際のマージ（リリース）は人間に委ねられる。
+サブ Issue がすべて Close されると `epic-issue` ワーカーがエピックブランチからまとめてPRを作る。エピックPRは `triage-pr` がマージ可能と判定してもマージせず `cc-release-ready` を付けるだけで、実際のマージ（リリース）は人間に委ねられる。
 
 ### UIデザイン先行ワークフロー
 
-UI実装 Issue について、実装の前に Pencil（`.pen`）でデザインを作り、独立したPRとしてマージしてから実装へ進むフロー。デザインを実装PRとは別に単体でレビュー・合意でき、合意済みデザインがリポジトリに永続化される。
-
-`uiDesign.enabled` によるオプトインで、既定（`false`）では2つのワーカーが起動しないため、Pencil を使っていないリポジトリの挙動は本機能の追加前と完全に一致する。
+UI実装 Issue について、実装の前に Pencil（`.pen`）でデザインを作り、独立したPRとしてマージしてから実装へ進むフロー。`uiDesign.enabled` によるオプトインで、既定（`false`）では関連ワーカーが起動しない。
 
 | キー | 既定 | 意味 |
 |---|---|---|
-| `uiDesign.enabled` | `false` | 有効化。`false` の間は `triage-created-issue` がUI判定を行わず、2つのワーカーも起動しない |
+| `uiDesign.enabled` | `false` | 有効化 |
 | `uiDesign.designDir` | `"designs"` | `.pen` とスナップショットの配置先（リポジトリルートからの相対パス） |
-| `uiDesign.yolo` | `false` | デザインPRを自動レビュー・自動マージへ流すか。`true` のときだけデザインPRに `cc-triage-scope` を付ける |
+| `uiDesign.yolo` | `false` | `true` でデザインPRに `cc-triage-scope` を付け、既存フローで自動レビュー・自動マージへ流す |
 
 ```text
-cc-issue-created + triage-created-issue（ルーティング）
-  ├─ UI実装タスクでない → cc-exec-issue（従来どおり）
+triage-created-issue（ルーティング）
+  ├─ UI実装タスクでない → cc-exec-issue
   └─ UI実装タスク       → cc-create-ui-design
-        → create-ui-design ワーカー
-           ・.pen を作成/更新 + snapshots/ に PNG 出力
-           ・ブランチ cc-ui-design-<N> を push しデザインPRを作成（Refs #N。closing keyword は使わない）
-           ・PR に cc-ui-design、Issue に cc-ui-design-pr-created を付与
-        → yolo: true  → triage-pr / fix-review-point / resolve-conflict（既存フローでレビュー・マージ）
-           yolo: false → 人がデザインPRをレビュー・マージ
-        → apply-ui-design ワーカー
-           ・デザインPRが MERGED になるまで skip
-           ・Issue description に「## UIデザイン」セクションを追記
-           ・cc-ui-design-ready + cc-exec-issue を付与
-        → exec-issue（デザインを参照元として実装）
+        → create-ui-design: .pen + snapshots を作り、デザインPR（cc-ui-design）を作成
+        → yolo: true なら自動レビュー・マージ / false なら人がレビュー・マージ
+        → apply-ui-design: マージ後に Issue description へ「## UIデザイン」を追記し cc-exec-issue を付与
+        → exec-issue: デザインを参照元として実装
 ```
 
-`triage-pr` は `cc-ui-design` 付きPRをコードレビューではなくデザイン向けの観点（差分が `.pen` とPNGに限定されているか、スナップショットからデザイン意図が読み取れるか、Issue 要件を満たしているか）で評価する。
-
-デザインが不要と判明した場合は `create-ui-design` が理由をコメントして `cc-ui-design-ready` + `cc-exec-issue` を付与し、人手を介さず実装へ復帰する。Pencil が使えない環境やデザインPRが却下された場合は `cc-need-human-check` で停止する。
+デザインが不要と判明した場合は `create-ui-design` が理由をコメントして実装へ復帰する。Pencil が使えない環境やデザインPRが却下された場合は `cc-need-human-check` で停止する。
 
 ## Slack通知
 
-環境変数 `CLAUDE_TASK_WORKER_SLACK_WEBHOOK_URL` に Slack Incoming Webhook URL を設定すると、各ワーカーのタスク完了時・失敗時に通知が送られる。未設定なら送信されない。
+環境変数 `CLAUDE_TASK_WORKER_SLACK_WEBHOOK_URL` に Incoming Webhook URL を設定すると、タスクの完了時・失敗時に通知が送られる。未設定なら送信されない。
 
 ```bash
 export CLAUDE_TASK_WORKER_SLACK_WEBHOOK_URL=https://hooks.slack.com/services/xxx/yyy/zzz
 claude-task-worker all
 ```
 
-通知には Claude API の使用状況（5時間/7日間の利用率とリセット時刻）も含まれる。使用状況の取得は macOS では `security`（Keychain）、それ以外では `~/.claude/.credentials.json` を使う。あわせて [RunCat Neo](https://kyome.io/runcat/) 用のスナップショットを `~/.claude/runcat-usage.json`（`RUNCAT_OUT_FILE` で変更可）へ原子的に書き出す（Webhook 未設定でも更新される）。取得結果は360秒キャッシュされるため、値は最大6分古くなりうる。
-
-クラウド実行（`--cloud`）のタスクは、通知の先頭行にクラウドセッションのURL（`https://claude.ai/code/<id>`）が入る。Slack で本文が折りたたまれても先頭行は見えるため。
+通知には Claude API の使用状況も含まれる。あわせて [RunCat Neo](https://kyome.io/runcat/) 用のスナップショットを `~/.claude/runcat-usage.json`（`RUNCAT_OUT_FILE` で変更可）へ書き出す。クラウド実行のタスクは通知の先頭行にセッションURLが入る。
 
 ## プロセス管理
 
-実行中のタスクはリアルタイムのステータステーブルで表示される。
-
-- タスクID・タイトル・ステータス（running/completed/failed）・開始時刻・経過時間を表示
-- `mode: "herdr"` では実行中の行に agent ステータスが併記される（`running:working` / `running:blocked`）
-- 同一 Issue/PR の重複実行を自動防止
-- SIGTERM/SIGINT で全子プロセスを graceful shutdown（もう一度送ると強制終了し、ラベル・worktree の後片付けを試みる）
-- 前回の異常終了で残った worktree はワーカー起動時に自動回収される（実行中タスク・対話セッションが掴んでいるものは保護される）
-
-### タスク実行のガード
-
-ワーカーは応答するユーザーがいない状態でスキルを起動するため、処理が未完のままセッションが終了してラベルだけ進む事故を防ぐガードを持つ。
+実行中のタスクはリアルタイムのステータステーブルで表示される（タスクID・タイトル・ステータス・開始時刻・経過時間）。SIGTERM/SIGINT で graceful shutdown し、もう一度送ると強制終了してラベル・worktree の後片付けを試みる。前回の異常終了で残った worktree はワーカー起動時に自動回収される。
 
-- **バックグラウンド実行の無効化**: `CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1` を全タスクへ注入し、Bash の `run_in_background` やサブエージェントの自動バックグラウンド化を止める
-- **ツールの無効化**: `--disallowedTools` で `Monitor` / `ScheduleWakeup` / `AskUserQuestion` / `EnterPlanMode` / `Cron*` / `RemoteTrigger` / `EnterWorktree` を無効化する
-- **自律実行原則の注入**: `--append-system-prompt` で「ユーザーに質問しない・全ステップを完遂してから終了する・曖昧なら安全側を選ぶ・サブエージェントの完了報告を検証する」および CodeGraph 優先のコード探索方針を注入する
-- **完了検証**: `exec-issue` / `epic-issue` は PR の実在（または Issue のクローズ）を確認できるまで `cc-pr-created` を付けず、確認できなければ `cc-need-human-check` を付けて Issue にコメントを残す
-- **空振り検知**: 正常終了しても出力が空のセッションは失敗として分類し、失敗通知（stderr の末尾を含む）を送る
-- **起動プロセスの後片付け**: スキル終了時に `Stop` フックが `docker compose down` と、worktree を作業ディレクトリに持つ残留プロセスの `SIGTERM` をベストエフォートで実行する（worktree はスキル完了直後に削除されるため、残留プロセスが削除の妨げになるのを防ぐ）
+ワーカーは応答するユーザーがいない状態でスキルを起動するため、処理が未完のままラベルだけ進む事故を防ぐガードを持つ（バックグラウンド実行と対話系ツールの無効化、自律実行原則のシステムプロンプト注入、PR 実在の完了検証、空出力セッションの失敗扱い、`Stop` フックによる残留プロセスの停止）。
 
 ## 開発
 
 ```bash
 npm install
-npm run build         # 型チェック（tsc --noEmit）+ esbuild で dist/index.js にバンドル
+npm run build         # 型チェック + esbuild で dist/index.js にバンドル
 npm run dev           # 型チェックの watch モード
-npm test              # ユニットテスト（node --experimental-strip-types --test）
+npm test              # ユニットテスト
 npm run lint          # ESLint（--fix で自動修正）
-npm run format        # Prettier で整形（format:check でチェックのみ）
+npm run format        # Prettier で整形
 ```
 
 開発版をローカルから使う場合は `npm install && npm run build && npm link`。

package/dist/index.js

@@ -12,6 +12,7 @@ var __export = (target, all) => {
 // src/table.ts
 var table_exports = {};
 __export(table_exports, {
+  CONTROL_CHARS: () => CONTROL_CHARS,
   LOG_DISPLAY_LIMIT: () => LOG_DISPLAY_LIMIT,
   TASK_DISPLAY_LIMIT: () => TASK_DISPLAY_LIMIT,
   buildLogTableLines: () => buildLogTableLines,
@@ -190,7 +191,8 @@ var init_table = __esm({
     rawLog = console.log.bind(console);
     rawClear = console.clear.bind(console);
     consoleCaptured = false;
-    CONTROL_CHARS = /\x1b\[[0-9;?]*[ -/]*[@-~]|[\x00-\x08\x0b-\x1f\x7f]/g;
+    CONTROL_CHARS = // eslint-disable-next-line no-control-regex -- ANSI/制御文字を意図的に対象にする
+    /\x1b\][^\x07\x1b]*(?:\x07|\x1b\\)|\x1b\[[0-9;?]*[ -/]*[@-~]|[\x00-\x08\x0b-\x1f\x7f]/g;
   }
 });
 
@@ -588,6 +590,7 @@ __export(herdr_runner_exports, {
   buildHerdrTaskResult: () => buildHerdrTaskResult,
   createCompletionTracker: () => createCompletionTracker,
   extractCloudSessionId: () => extractCloudSessionId,
+  normalizePtyOutput: () => normalizePtyOutput,
   observeAgentStatus: () => observeAgentStatus,
   startHerdrTask: () => startHerdrTask,
   stopHerdrTask: () => stopHerdrTask,
@@ -629,6 +632,9 @@ function observeAgentStatus(tracker, status) {
 function extractCloudSessionId(text) {
   return CLOUD_SESSION_URL_RE.exec(text)?.[1] ?? CLOUD_SESSION_CREATED_RE.exec(text)?.[1];
 }
+function normalizePtyOutput(text) {
+  return text.replace(CONTROL_CHARS, "");
+}
 function buildHerdrTaskResult(paneOutput, options) {
   const report = options?.report?.trim() ?? "";
   if (report !== "") {
@@ -810,6 +816,7 @@ var AGENT_POLL_INTERVAL_MS, PANE_OUTPUT_LINES, CLOUD_SESSION_URL_RE, CLOUD_SESSI
 var init_herdr_runner = __esm({
   "src/herdr-runner.ts"() {
     "use strict";
+    init_table();
     init_transcript();
     AGENT_POLL_INTERVAL_MS = 3 * 1e3;
     PANE_OUTPUT_LINES = 300;
@@ -1635,7 +1642,7 @@ import { readFileSync, writeFileSync } from "node:fs";
 import { isAbsolute, join, normalize, sep as SEP } from "node:path";
 
 // src/dispatch-args.ts
-var FLAG_INCOMPATIBLE_COMMANDS = ["init", "install", "update", "usage", "version"];
+var FLAG_INCOMPATIBLE_COMMANDS = ["init", "install", "update", "cloud-setup", "usage", "version"];
 function collectFlagValues(argv, flag) {
   const values = [];
   for (let i = 0; i < argv.length; i++) {
@@ -1888,9 +1895,9 @@ function checkCloudAuth(input) {
 function checkCloudConfig(input) {
   if (!input.cloud) return [];
   const errors = [];
-  if (input.mode !== "herdr") {
+  if (input.scriptAvailable === false) {
     errors.push(
-      `--cloud requires mode "herdr" but mode is "${input.mode}" (creating a new cloud session requires a TTY, which "default" mode's spawn does not have). Set mode to "herdr" in config.json, or drop the --cloud flag.`
+      `--cloud requires a pty, provided via the "script" command (creating a new cloud session requires a TTY, which the worker's spawn does not have on its own). "script" is unavailable \u2014 either the platform is not darwin/linux, or "script" is not on PATH. Drop the --cloud flag, or run on darwin/linux where "script" is available.`
     );
   }
   if (input.auth !== void 0) errors.push(...checkCloudAuth(input.auth));
@@ -2521,15 +2528,26 @@ ${principles}`;
 function shellQuote2(value) {
   return `'${value.replace(/'/g, "'\\''")}'`;
 }
+function buildScriptCommand(command, args, platform = process.platform) {
+  if (platform === "darwin") {
+    return { command: "script", args: ["-q", "/dev/null", command, ...args] };
+  }
+  if (platform === "linux") {
+    return { command: "script", args: ["-qec", [command, ...args].map(shellQuote2).join(" "), "/dev/null"] };
+  }
+  throw new Error(`unsupported platform for script(1): ${platform}`);
+}
 function buildClaudeExecution(invocation) {
   return {
     command: CLAUDE_COMMAND,
     args: buildClaudeArgs(invocation),
-    ...invocation.mode === "herdr" ? { prompt: invocation.prompt } : {}
+    // クラウド実行では `-p` を付けない代わりに `--cloud` の値（初期プロンプト）として
+    // 渡すため、mode に関わらずプロンプトを返す。
+    ...invocation.mode === "herdr" || invocation.cloud === true ? { prompt: invocation.prompt } : {}
   };
 }
 function buildClaudeEnv(mode, cloud) {
-  const base = mode === "herdr" ? { CLAUDE_CODE_DISABLE_BACKGROUND_TASKS: CLAUDE_SPAWN_ENV.CLAUDE_CODE_DISABLE_BACKGROUND_TASKS } : { ...CLAUDE_SPAWN_ENV };
+  const base = mode === "herdr" || cloud ? { CLAUDE_CODE_DISABLE_BACKGROUND_TASKS: CLAUDE_SPAWN_ENV.CLAUDE_CODE_DISABLE_BACKGROUND_TASKS } : { ...CLAUDE_SPAWN_ENV };
   if (!cloud) return base;
   return { ...base, CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC: "1" };
 }
@@ -2827,13 +2845,55 @@ async function flagOrphanedCloudSession(target, id, reason, cloudSessionId) {
     console.error(`[worker] failed to comment on ${target} #${id} about the orphaned cloud session: ${err}`);
   });
 }
+async function createCloudSession(args, initialPrompt, cwd, env) {
+  const { extractCloudSessionId: extractCloudSessionId2, normalizePtyOutput: normalizePtyOutput2 } = await Promise.resolve().then(() => (init_herdr_runner(), herdr_runner_exports));
+  const spec = buildScriptCommand("claude", buildCloudCreateArgs(args, initialPrompt));
+  const child = spawn(spec.command, spec.args, {
+    stdio: ["ignore", "pipe", "pipe"],
+    ...cwd ? { cwd } : {},
+    ...env ? { env: { ...process.env, ...env } } : {}
+  });
+  let output = "";
+  return await new Promise((resolve3, reject) => {
+    let settled = false;
+    const finish = (err, sessionId) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      clearInterval(abortCheck);
+      if (err) {
+        child.kill();
+        reject(err);
+      } else {
+        resolve3(sessionId);
+      }
+    };
+    const scan = () => {
+      const sessionId = extractCloudSessionId2(normalizePtyOutput2(output));
+      if (sessionId) finish(void 0, sessionId);
+    };
+    child.stdout?.on("data", (chunk) => {
+      output += chunk.toString("utf-8");
+      scan();
+    });
+    child.on("error", (err) => finish(new Error(`failed to spawn the cloud session command: ${err.message}`)));
+    child.on("close", () => {
+      scan();
+      finish(new Error(`the cloud session command exited without a session id (output tail: ${output.slice(-1e3)})`));
+    });
+    const timer = setTimeout(
+      () => finish(new Error(`timed out waiting for the cloud session id (output tail: ${output.slice(-1e3)})`)),
+      CLOUD_SESSION_TIMEOUT_MS
+    );
+    const abortCheck = setInterval(() => {
+      if (herdrAbortSignal.aborted) {
+        finish(new Error("the worker is shutting down before the cloud session could be created"));
+      }
+    }, CLOUD_SESSION_POLL_INTERVAL_MS);
+  });
+}
 async function runViaCloud(args, prompt, id, onComplete, cwd, env, cloudTarget, model) {
-  const herdrRunnerMod = await Promise.resolve().then(() => (init_herdr_runner(), herdr_runner_exports));
-  const { taskTabLabel: taskTabLabel2, waitForPaneReady: waitForPaneReady3, extractCloudSessionId: extractCloudSessionId2 } = herdrRunnerMod;
-  const herdrMod = await Promise.resolve().then(() => (init_herdr(), herdr_exports));
-  const { tabCreate: tabCreate2, tabClose: tabClose2, paneSendText: paneSendText2, paneSendKeys: paneSendKeys2, paneRead: paneRead2, getCurrentWorkspaceId: getCurrentWorkspaceId2 } = herdrMod;
   herdrTasks.set(id, { paneId: "", tabId: "" });
-  const label = taskTabLabel2(resolveProjectName(), id);
   const initialPrompt = buildCloudPrompt(
     prompt,
     model ?? "",
@@ -2842,39 +2902,7 @@ async function runViaCloud(args, prompt, id, onComplete, cwd, env, cloudTarget,
   let result;
   let cloudSessionId;
   try {
-    const created = await tabCreate2({ label, cwd: cwd ?? process.cwd(), workspaceId: getCurrentWorkspaceId2(), env });
-    herdrTasks.set(id, created);
-    try {
-      const ready = await waitForPaneReady3(created.paneId, herdrMod);
-      if (!ready) {
-        console.warn(`[worker] pane ${created.paneId} produced no prompt before the timeout, launching anyway`);
-      }
-      const command = ["claude", ...buildCloudCreateArgs(args, initialPrompt)].map(shellQuote2).join(" ");
-      await paneSendText2(created.paneId, command);
-      await paneSendKeys2(created.paneId, "enter");
-      const deadline = Date.now() + CLOUD_SESSION_TIMEOUT_MS;
-      for (; ; ) {
-        if (herdrAbortSignal.aborted) {
-          throw new Error("the worker is shutting down before the cloud session could be created");
-        }
-        let content = "";
-        try {
-          content = await paneRead2(created.paneId);
-        } catch (err) {
-          console.error(`[worker] failed to read pane ${created.paneId} while waiting for the cloud session: ${err}`);
-        }
-        cloudSessionId = extractCloudSessionId2(content);
-        if (cloudSessionId) break;
-        if (Date.now() >= deadline) {
-          throw new Error(`timed out waiting for the cloud session id (pane tail: ${content.slice(-1e3)})`);
-        }
-        await new Promise((resolve3) => setTimeout(resolve3, CLOUD_SESSION_POLL_INTERVAL_MS));
-      }
-    } finally {
-      await tabClose2(created.tabId).catch((err) => {
-        console.error(`[worker] failed to close cloud task tab ${created.tabId}: ${err}`);
-      });
-    }
+    cloudSessionId = await createCloudSession(args, initialPrompt, cwd, env);
     const createOutput = `[worker] created cloud session ${cloudSessionId} with the task's initial prompt`;
     if (!cloudTarget) {
       console.warn(`[worker] #${id} has no completion-detection target, treating session creation as completion`);
@@ -2922,7 +2950,8 @@ async function runViaCloud(args, prompt, id, onComplete, cwd, env, cloudTarget,
     console.error(`[worker] failed to run #${id} via cloud: ${err}`);
     let orphanNote = "[worker] note: with the 1-command launch, the cloud session may already have started working independently even though this task is being reported as failed locally (orphaned session).";
     if (cloudTarget) {
-      await flagOrphanedCloudSession(cloudTarget, id, "session-id", cloudSessionId);
+      const reason = herdrAbortSignal.aborted ? "shutdown" : "session-id";
+      await flagOrphanedCloudSession(cloudTarget, id, reason, cloudSessionId);
       orphanNote += " added cc-need-human-check so a human can verify whether it completed on its own.";
     }
     result = {
@@ -2948,11 +2977,11 @@ function run(command, args, id, title, workerName, path2, onComplete, cwd, env,
   });
   ensureRenderInterval();
   renderTable();
+  if (cloud) {
+    void runViaCloud(args, prompt ?? "", id, onComplete, cwd, env, cloudTarget, model);
+    return;
+  }
   if (getRunMode() === "herdr") {
-    if (cloud) {
-      void runViaCloud(args, prompt ?? "", id, onComplete, cwd, env, cloudTarget, model);
-      return;
-    }
     void runViaHerdr(args, prompt ?? "", id, onComplete, cwd, env);
     return;
   }
@@ -5089,6 +5118,78 @@ async function install() {
   console.log("[install] Done.");
 }
 
+// src/commands/cloud-setup.ts
+import { mkdir as mkdir3, writeFile as writeFile3, readFile as readFile2 } from "node:fs/promises";
+import { homedir as homedir6 } from "node:os";
+import { join as join8 } from "node:path";
+var LOG_PREFIX = "cloud-setup";
+var CLOUD_DEFAULT_PERMISSION_MODE = "auto";
+var CLOUD_SETTINGS_DEFAULTS = {
+  outputStyle: "Proactive",
+  language: "Japanese"
+};
+function claudeSettingsPath() {
+  const dir = process.env.CLAUDE_CONFIG_DIR;
+  return join8(dir && dir.length > 0 ? dir : join8(homedir6(), ".claude"), "settings.json");
+}
+function withCloudDefaults(existing, force) {
+  const parsed = existing === null ? {} : JSON.parse(existing);
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+    throw new Error("not a JSON object");
+  }
+  const settings = { ...parsed };
+  const current = settings["permissions"] ?? {};
+  if (typeof current !== "object" || current === null || Array.isArray(current)) {
+    throw new Error("`permissions` is not an object");
+  }
+  const permissions = { ...current };
+  let changed = false;
+  const set = (target, key, value) => {
+    if (key in target && !force) return;
+    if (target[key] === value) return;
+    target[key] = value;
+    changed = true;
+  };
+  set(permissions, "defaultMode", CLOUD_DEFAULT_PERMISSION_MODE);
+  for (const [key, value] of Object.entries(CLOUD_SETTINGS_DEFAULTS)) set(settings, key, value);
+  if (!changed) return null;
+  return `${JSON.stringify({ ...settings, permissions }, null, 2)}
+`;
+}
+async function writeClaudeSettings(force) {
+  const path2 = claudeSettingsPath();
+  let existing;
+  try {
+    existing = await readFile2(path2, "utf-8");
+  } catch {
+    existing = null;
+  }
+  let next;
+  try {
+    next = withCloudDefaults(existing, force);
+  } catch (e) {
+    console.log(`[${LOG_PREFIX}] Skipped: ${path2} (${e instanceof Error ? e.message : String(e)})`);
+    return;
+  }
+  if (next === null) {
+    console.log(`[${LOG_PREFIX}] Already set: ${path2}`);
+    return;
+  }
+  try {
+    await mkdir3(join8(path2, ".."), { recursive: true });
+    await writeFile3(path2, next, "utf-8");
+  } catch (e) {
+    console.log(`[${LOG_PREFIX}] Failed to write ${path2}: ${e instanceof Error ? e.message : String(e)}`);
+    return;
+  }
+  console.log(`[${LOG_PREFIX}] ${existing === null ? "Created" : "Updated"}: ${path2}`);
+}
+async function cloudSetup(options = {}) {
+  await writeClaudeSettings(options.force ?? false);
+  await ensureCodegraphGitIgnore(LOG_PREFIX);
+  console.log(`[${LOG_PREFIX}] Done.`);
+}
+
 // src/commands/update.ts
 init_run_command();
 var PLUGIN_NAME2 = "claude-task-worker";
@@ -5144,14 +5245,14 @@ async function update() {
 
 // src/commands/version.ts
 import { readFileSync as readFileSync5 } from "node:fs";
-import { dirname as dirname3, join as join8 } from "node:path";
+import { dirname as dirname3, join as join9 } from "node:path";
 import { fileURLToPath } from "node:url";
 import { styleText } from "node:util";
 var REGISTRY_URL = "https://registry.npmjs.org/claude-task-worker/latest";
 var FETCH_TIMEOUT_MS = 3e3;
 function localVersion() {
   const here = dirname3(fileURLToPath(import.meta.url));
-  const pkgPath = join8(here, "..", "package.json");
+  const pkgPath = join9(here, "..", "package.json");
   const pkg = JSON.parse(readFileSync5(pkgPath, "utf8"));
   return pkg.version ?? "unknown";
 }
@@ -5217,6 +5318,7 @@ Commands:
   init [--force]  Create required GitHub labels and config file (use --force to overwrite existing files)
   install           Add the claude-task-worker marketplace, install the plugin, and install/update the CLI
   update            Update the claude-task-worker plugin/marketplace and the CLI itself
+  cloud-setup [--force]  Prepare a cloud session VM (writes permission mode, output style, and language into ~/.claude/settings.json). Meant for a cloud environment setup script
   usage             Notify current usage to Slack
   version           Print the installed claude-task-worker CLI version (aliases: --version, -v)
 
@@ -5267,7 +5369,7 @@ if (!workerType) {
   printUsage();
   process.exit(1);
 }
-if (workerType !== "all" && workerType !== "yolo" && workerType !== "init" && workerType !== "install" && workerType !== "update" && workerType !== "usage" && !WORKERS[workerType]) {
+if (workerType !== "all" && workerType !== "yolo" && workerType !== "init" && workerType !== "install" && workerType !== "update" && workerType !== "cloud-setup" && workerType !== "usage" && !WORKERS[workerType]) {
   console.error(`Unknown command: ${workerType}`);
   printUsage();
   process.exit(1);
@@ -5344,13 +5446,27 @@ async function readCloudAuthStatus() {
     return { kind: "unknown" };
   }
 }
+async function resolveScriptAvailable() {
+  try {
+    buildScriptCommand("true", []);
+  } catch {
+    return false;
+  }
+  try {
+    await execFileAsync4("which", ["script"]);
+    return true;
+  } catch {
+    return false;
+  }
+}
 async function assertCloudAvailable() {
   const cloud = hasCloudFlag();
   const labelReady = cloud ? await createLabel(CLOUD_DONE_LABEL, "33cfff", true) : true;
   const status = cloud ? await readCloudAuthStatus() : void 0;
+  const scriptAvailable = cloud ? await resolveScriptAvailable() : void 0;
   const errors = checkCloudConfig({
     cloud,
-    mode: getRunMode(),
+    scriptAvailable,
     auth: status ? { status, baseUrl: process.env.ANTHROPIC_BASE_URL } : void 0
   });
   if (!labelReady) {
@@ -5452,6 +5568,10 @@ if (hasProjectFilter()) {
   (async () => {
     await update();
   })();
+} else if (workerType === "cloud-setup") {
+  (async () => {
+    await cloudSetup({ force: process.argv.slice(3).includes("--force") });
+  })();
 } else if (workerType === "usage") {
   (async () => {
     const text = await buildTokenLimitText();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-task-worker",
-  "version": "0.99.0",
+  "version": "0.101.0",
   "description": "CLI tool that polls GitHub Issues/PRs and delegates work to Claude CLI",
   "type": "module",
   "main": "dist/index.js",