docs: hook suppressOutput TUI behavior + marketplace ref/sha pinning

docs/cli/configuration/plugins.mdx

@@ -170,9 +170,7 @@ A plugin can only exist at one scope. To change scope, uninstall first and reins
 
 Plugins are versioned by Git commit hash, not semantic version. When you update a plugin, Droid fetches the latest commit from the marketplace repository.
 
-<Note>
-Version pinning is not supported. Updates always fetch the latest version from the marketplace.
-</Note>
+To pin a marketplace to a specific version, set `ref` (a branch or tag) or `sha` (a full 40-character commit SHA) on the marketplace source. See [Pinning a marketplace to a ref or commit](#pinning-a-marketplace-to-a-ref-or-commit) below.
 
 ## Marketplaces
 
@@ -240,6 +238,45 @@ The installation scope depends on where the setting is defined:
 - User settings → `user` scope
 - Project settings → `project` scope
 
+### Pinning a marketplace to a ref or commit
+
+By default Droid tracks the marketplace's default branch and pulls the latest commit on update. You can pin a marketplace to a specific Git ref or commit by adding `ref` or `sha` to the source object.
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `ref` | string | Branch or tag to track (e.g. `"main"`, `"v1.2.0"`, `"staging"`). |
+| `sha` | string | Full 40-character commit SHA. When set, the marketplace stays on this exact commit and `droid plugin marketplace update` is a no-op. |
+
+`ref` and `sha` are supported on the `github`, `url`, and `git-subdir` source types. Use `sha` for hard pins; use `ref` to follow a branch or tag.
+
+```json
+{
+  "extraKnownMarketplaces": {
+    "your-org-internal-plugins": {
+      "source": {
+        "source": "github",
+        "repo": "your-org/internal-plugins",
+        "ref": "v1.2.0"
+      }
+    },
+    "your-org-frozen-plugins": {
+      "source": {
+        "source": "github",
+        "repo": "your-org/internal-plugins",
+        "sha": "1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b"
+      }
+    }
+  }
+}
+```
+
+From the CLI, pass `--ref` or `--sha` when adding a marketplace:
+
+```bash
+droid plugin marketplace add https://github.com/your-org/internal-plugins --ref v1.2.0
+droid plugin marketplace add https://github.com/your-org/internal-plugins --sha 1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b
+```
+
 ## Discovering plugins
 
 ### Official Factory plugins

docs/enterprise/enterprise-plugin-registry.mdx

@@ -207,13 +207,39 @@ Pre-installed plugins:
 
 Plugins are versioned by Git commit hash. When a plugin is updated, Droid fetches the latest commit from the marketplace.
 
-To control versions, use Git branches:
-- `main` - Production-ready for all users
-- `staging` - For early adopters
-- `dev` - For internal testing
+To control versions, pin the marketplace source itself with `ref` (branch or tag) or `sha` (full commit SHA):
+
+```json
+{
+  "extraKnownMarketplaces": {
+    "acme-corp-plugins": {
+      "source": {
+        "source": "github",
+        "repo": "your-org/droid-plugins",
+        "ref": "v2.4.0"
+      }
+    },
+    "acme-corp-plugins-frozen": {
+      "source": {
+        "source": "github",
+        "repo": "your-org/droid-plugins",
+        "sha": "1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b"
+      }
+    }
+  }
+}
+```
+
+Common patterns:
+- `ref: "main"` — production-ready for all users (default behavior)
+- `ref: "staging"` — early-adopter channel
+- `ref: "v1.2.0"` — pin to a release tag
+- `sha: "<40-char SHA>"` — hard pin to a specific commit; `droid plugin marketplace update` is a no-op
+
+See [Plugins · Pinning a marketplace to a ref or commit](/cli/configuration/plugins#pinning-a-marketplace-to-a-ref-or-commit) for the full source schema.
 
 <Note>
-Version pinning via the `version` field is not currently supported. The field is for documentation only.
+Version pinning via the per-plugin `version` field is not currently supported. To pin a plugin's version, pin the marketplace it lives in via `ref` or `sha`.
 </Note>
 
 ## Private repository access

docs/enterprise/hierarchical-settings-and-org-control.mdx

@@ -206,13 +206,25 @@ Below is the full schema for org-managed settings. These are configured by org a
         <ResponseField name="repo" type="string" required>
           GitHub repository in `owner/repo` format.
         </ResponseField>
+        <ResponseField name="ref" type="string">
+          Optional Git branch or tag to track (e.g. `"main"`, `"v1.2.0"`).
+        </ResponseField>
+        <ResponseField name="sha" type="string">
+          Optional full 40-character commit SHA. When set, the marketplace is pinned to this exact commit.
+        </ResponseField>
       </Expandable>
       <Expandable title="url">
         <ResponseField name="source" type="string" required>
           Must be `"url"`.
         </ResponseField>
         <ResponseField name="url" type="string" required>
-          URL of the marketplace manifest.
+          Git repository URL of the marketplace (e.g. `https://gitlab.com/company/plugins.git`).
+        </ResponseField>
+        <ResponseField name="ref" type="string">
+          Optional Git branch or tag to track.
+        </ResponseField>
+        <ResponseField name="sha" type="string">
+          Optional full 40-character commit SHA to pin to.
         </ResponseField>
       </Expandable>
       <Expandable title="local">

docs/guides/building/building-plugins.mdx

@@ -340,7 +340,7 @@ Use semantic versioning in your plugin manifest for documentation purposes:
 - **Patch** (1.0.0 → 1.0.1): Bug fixes
 
 <Note>
-Droid tracks plugin versions by Git commit hash, not semantic version. When users update a plugin, they always get the latest commit from the marketplace. Version pinning is not currently supported.
+Droid tracks plugin versions by Git commit hash, not semantic version. By default, updating a plugin fetches the latest commit from the marketplace. To pin a plugin to a specific version, pin the marketplace it lives in by setting `ref` (branch or tag) or `sha` (full commit SHA) on the marketplace source — see [Pinning a marketplace to a ref or commit](/cli/configuration/plugins#pinning-a-marketplace-to-a-ref-or-commit).
 </Note>
 
 ## Claude Code compatibility

docs/jp/cli/configuration/plugins.mdx

@@ -158,9 +158,7 @@ my-plugin/
 
 プラグインはセマンティックバージョンではなく、Gitコミットハッシュによってバージョニングされます。プラグインを更新すると、Droidはマーケットプレイスリポジトリから最新のコミットを取得します。
 
-<Note>
-バージョン固定はサポートされていません。更新では常にマーケットプレイスから最新バージョンを取得します。
-</Note>
+マーケットプレイスを特定のバージョンに固定するには、マーケットプレイスソースに `ref`（ブランチまたはタグ）または `sha`（40文字のフルコミットSHA）を設定します。下記の[マーケットプレイスをrefまたはコミットに固定する](#%E3%83%9E%E3%83%BC%E3%82%B1%E3%83%83%E3%83%88%E3%83%97%E3%83%AC%E3%82%A4%E3%82%B9%E3%82%92ref%E3%81%BE%E3%81%9F%E3%81%AF%E3%82%B3%E3%83%9F%E3%83%83%E3%83%88%E3%81%AB%E5%9B%BA%E5%AE%9A%E3%81%99%E3%82%8B)を参照してください。
 
 ## マーケットプレイス
 
@@ -222,6 +220,45 @@ Droidが起動すると、自動的に以下を実行します：
 - ユーザー設定 → `user`スコープ
 - プロジェクト設定 → `project`スコープ
 
+### マーケットプレイスをrefまたはコミットに固定する
+
+デフォルトでは、Droidはマーケットプレイスのデフォルトブランチを追跡し、更新時に最新のコミットを取得します。ソースオブジェクトに `ref` または `sha` を追加することで、マーケットプレイスを特定のGit refまたはコミットに固定できます。
+
+| フィールド | 型 | 説明 |
+|-------|------|-------------|
+| `ref` | string | 追跡するブランチまたはタグ（例: `"main"`、`"v1.2.0"`、`"staging"`）。 |
+| `sha` | string | 40文字のフルコミットSHA。設定すると、マーケットプレイスはこのコミットに固定され、`droid plugin marketplace update` は何も行いません。 |
+
+`ref` と `sha` は `github`、`url`、`git-subdir` ソースタイプでサポートされています。ハードピンには `sha`、ブランチやタグを追跡するには `ref` を使用します。
+
+```json
+{
+  "extraKnownMarketplaces": {
+    "your-org-internal-plugins": {
+      "source": {
+        "source": "github",
+        "repo": "your-org/internal-plugins",
+        "ref": "v1.2.0"
+      }
+    },
+    "your-org-frozen-plugins": {
+      "source": {
+        "source": "github",
+        "repo": "your-org/internal-plugins",
+        "sha": "1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b"
+      }
+    }
+  }
+}
+```
+
+CLIからマーケットプレイスを追加する際は、`--ref` または `--sha` を渡します：
+
+```bash
+droid plugin marketplace add https://github.com/your-org/internal-plugins --ref v1.2.0
+droid plugin marketplace add https://github.com/your-org/internal-plugins --sha 1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b
+```
+
 ## プラグインの発見
 
 ### 公式Factoryプラグイン

docs/jp/enterprise/enterprise-plugin-registry.mdx

@@ -207,13 +207,39 @@ plugins/
 
 プラグインはGitコミットハッシュでバージョン管理されます。プラグインが更新されると、Droidはマーケットプレイスから最新のコミットを取得します。
 
-バージョンを制御するには、Gitブランチを使用します：
-- `main` - すべてのユーザー向けのプロダクション準備完了
-- `staging` - 早期採用者向け
-- `dev` - 内部テスト向け
+バージョンを制御するには、マーケットプレイスソース自体に `ref`（ブランチまたはタグ）または `sha`（フルコミットSHA）を設定して固定します：
+
+```json
+{
+  "extraKnownMarketplaces": {
+    "acme-corp-plugins": {
+      "source": {
+        "source": "github",
+        "repo": "your-org/droid-plugins",
+        "ref": "v2.4.0"
+      }
+    },
+    "acme-corp-plugins-frozen": {
+      "source": {
+        "source": "github",
+        "repo": "your-org/droid-plugins",
+        "sha": "1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b"
+      }
+    }
+  }
+}
+```
+
+一般的なパターン：
+- `ref: "main"` — すべてのユーザー向けのプロダクション準備完了（デフォルトの動作）
+- `ref: "staging"` — 早期採用者チャンネル
+- `ref: "v1.2.0"` — リリースタグに固定
+- `sha: "<40文字のSHA>"` — 特定のコミットへのハードピン；`droid plugin marketplace update` は何も行いません
+
+完全なソーススキーマについては、[プラグイン · マーケットプレイスをrefまたはコミットに固定する](/jp/cli/configuration/plugins#%E3%83%9E%E3%83%BC%E3%82%B1%E3%83%83%E3%83%88%E3%83%97%E3%83%AC%E3%82%A4%E3%82%B9%E3%82%92ref%E3%81%BE%E3%81%9F%E3%81%AF%E3%82%B3%E3%83%9F%E3%83%83%E3%83%88%E3%81%AB%E5%9B%BA%E5%AE%9A%E3%81%99%E3%82%8B)を参照してください。
 
 <Note>
-`version`フィールドによるバージョン固定は現在サポートされていません。このフィールドはドキュメント用です。
+プラグインごとの `version` フィールドによるバージョン固定は現在サポートされていません。プラグインのバージョンを固定するには、`ref` または `sha` を使用してプラグインが含まれるマーケットプレイスを固定してください。
 </Note>
 
 ## プライベートリポジトリアクセス

docs/jp/enterprise/hierarchical-settings-and-org-control.mdx

@@ -187,6 +187,12 @@ User        → ~/.factory/
         <ResponseField name="repo" type="string" required>
           `owner/repo` 形式のGitHubリポジトリ。
         </ResponseField>
+        <ResponseField name="ref" type="string">
+          追跡するGitブランチまたはタグ（例: `"main"`、`"v1.2.0"`）。オプション。
+        </ResponseField>
+        <ResponseField name="sha" type="string">
+          40文字のフルコミットSHA。設定すると、マーケットプレイスはこのコミットに固定されます。オプション。
+        </ResponseField>
       </Expandable>
       <Expandable title="url">
         <ResponseField name="source" type="string" required>
@@ -195,6 +201,12 @@ User        → ~/.factory/
         <ResponseField name="url" type="string" required>
           マーケットプレイスマニフェストのURL。
         </ResponseField>
+        <ResponseField name="ref" type="string">
+          追跡するGitブランチまたはタグ。オプション。
+        </ResponseField>
+        <ResponseField name="sha" type="string">
+          固定する40文字のフルコミットSHA。オプション。
+        </ResponseField>
       </Expandable>
       <Expandable title="local">
         <ResponseField name="source" type="string" required>

docs/jp/guides/building/building-plugins.mdx

@@ -340,7 +340,7 @@ my-marketplace/
 - **パッチ**（1.0.0 → 1.0.1）：バグ修正
 
 <Note>
-DroidはプラグインバージョンをセマンティックバージョンではなくGitコミットハッシュで追跡します。ユーザーがプラグインを更新すると、常にマーケットプレイスの最新コミットを取得します。バージョン固定は現在サポートされていません。
+DroidはプラグインバージョンをセマンティックバージョンではなくGitコミットハッシュで追跡します。デフォルトでは、プラグインを更新するとマーケットプレイスから最新のコミットを取得します。プラグインを特定のバージョンに固定するには、マーケットプレイスソースに `ref`（ブランチまたはタグ）または `sha`（フルコミットSHA）を設定して、プラグインが含まれるマーケットプレイスを固定してください。詳細は[マーケットプレイスをrefまたはコミットに固定する](/jp/cli/configuration/plugins#%E3%83%9E%E3%83%BC%E3%82%B1%E3%83%83%E3%83%88%E3%83%97%E3%83%AC%E3%82%A4%E3%82%B9%E3%82%92ref%E3%81%BE%E3%81%9F%E3%81%AF%E3%82%B3%E3%83%9F%E3%83%83%E3%83%88%E3%81%AB%E5%9B%BA%E5%AE%9A%E3%81%99%E3%82%8B)を参照してください。
 </Note>
 
 ## Claude Code互換性

docs/jp/reference/hooks-reference.mdx

@@ -411,7 +411,7 @@ Droidセッションが終了するときに実行されます。クリーンア
   "continue": true, // Whether Droid should continue after hook execution (default: true)
   "stopReason": "string", // Message shown when continue is false
 
-  "suppressOutput": true, // Hide stdout from transcript mode (default: false)
+  "suppressOutput": true, // フックが終了コード0で終了した場合、フックブロックをチャットビューから非表示にします（デフォルト: false）。詳細トランスクリプト（Ctrl+O）には引き続き表示され、失敗したフック（非ゼロ終了コード）は常に表示されます。
   "systemMessage": "string" // Optional warning message shown to the user
 }
 ```
@@ -666,7 +666,7 @@ if tool_name == "Read":
         output = {
             "decision": "approve",
             "reason": "Documentation file auto-approved",
-            "suppressOutput": True  # Don't show in transcript mode
+            "suppressOutput": True  # チャットビューからフックブロックを非表示にします（トランスクリプトには表示）
         }
         print(json.dumps(output))
         sys.exit(0)

docs/reference/hooks-reference.mdx

@@ -436,7 +436,7 @@ All hook types can include these optional fields:
   "continue": true, // Whether Droid should continue after hook execution (default: true)
   "stopReason": "string", // Message shown when continue is false
 
-  "suppressOutput": true, // Hide stdout from transcript mode (default: false)
+  "suppressOutput": true, // Hide the hook block from the chat view when the hook exits 0 (default: false). The block is still shown in the detailed transcript (Ctrl+O), and failing hooks (non-zero exit) are always rendered.
   "systemMessage": "string" // Optional warning message shown to the user
 }
 ```
@@ -703,7 +703,7 @@ if tool_name == "Read":
         output = {
             "decision": "approve",
             "reason": "Documentation file auto-approved",
-            "suppressOutput": True  # Don't show in transcript mode
+            "suppressOutput": True  # Hide the hook block from chat view (still in transcript)
         }
         print(json.dumps(output))
         sys.exit(0)