From 66335d3a49c43b4025ca67c5f50e1ccb35e3ea9c Mon Sep 17 00:00:00 2001
From: Vegard Stikbakke <vegard.stikbakke@gmail.com>
Date: Tue, 9 Jun 2026 13:23:07 +0200
Subject: [PATCH] feat(coding-agent): add experimental feature guard (#5547)

---
 packages/coding-agent/CHANGELOG.md            |  1 +
 .../coding-agent/src/core/experimental.ts     |  3 ++
 packages/coding-agent/src/core/index.ts       |  1 +
 .../coding-agent/test/experimental.test.ts    | 44 +++++++++++++++++++
 4 files changed, 49 insertions(+)
 create mode 100644 packages/coding-agent/src/core/experimental.ts
 create mode 100644 packages/coding-agent/test/experimental.test.ts

diff --git a/packages/coding-agent/CHANGELOG.md b/packages/coding-agent/CHANGELOG.md
index 260175d9..8235501a 100644
--- a/packages/coding-agent/CHANGELOG.md
+++ b/packages/coding-agent/CHANGELOG.md
@@ -4,6 +4,7 @@
 
 ### Added
 
+- Added `areExperimentalFeaturesEnabled` feature guard to allow users to opt-in to early features.
 - Added `ctx.isProjectTrusted()` for extensions to observe the effective project trust decision, including temporary trust decisions ([#5523](https://github.com/earendil-works/pi/issues/5523)).
 
 ### Fixed
diff --git a/packages/coding-agent/src/core/experimental.ts b/packages/coding-agent/src/core/experimental.ts
new file mode 100644
index 00000000..12d33c74
--- /dev/null
+++ b/packages/coding-agent/src/core/experimental.ts
@@ -0,0 +1,3 @@
+export function areExperimentalFeaturesEnabled(): boolean {
+	return process.env.PI_EXPERIMENTAL === "1";
+}
diff --git a/packages/coding-agent/src/core/index.ts b/packages/coding-agent/src/core/index.ts
index 71c45e9c..b7654f42 100644
--- a/packages/coding-agent/src/core/index.ts
+++ b/packages/coding-agent/src/core/index.ts
@@ -28,6 +28,7 @@ export {
 export { type BashExecutorOptions, type BashResult, executeBashWithOperations } from "./bash-executor.ts";
 export type { CompactionResult } from "./compaction/index.ts";
 export { createEventBus, type EventBus, type EventBusController } from "./event-bus.ts";
+export { areExperimentalFeaturesEnabled } from "./experimental.ts";
 // Extensions system
 export {
 	type AgentEndEvent,
diff --git a/packages/coding-agent/test/experimental.test.ts b/packages/coding-agent/test/experimental.test.ts
new file mode 100644
index 00000000..665616e8
--- /dev/null
+++ b/packages/coding-agent/test/experimental.test.ts
@@ -0,0 +1,44 @@
+import { afterEach, describe, expect, it } from "vitest";
+import { areExperimentalFeaturesEnabled } from "../src/core/experimental.ts";
+
+describe("areExperimentalFeaturesEnabled", () => {
+	const originalPiExperimental = process.env.PI_EXPERIMENTAL;
+
+	afterEach(() => {
+		if (originalPiExperimental === undefined) {
+			delete process.env.PI_EXPERIMENTAL;
+		} else {
+			process.env.PI_EXPERIMENTAL = originalPiExperimental;
+		}
+	});
+
+	it("returns false when PI_EXPERIMENTAL is unset", () => {
+		delete process.env.PI_EXPERIMENTAL;
+
+		expect(areExperimentalFeaturesEnabled()).toBe(false);
+	});
+
+	it("returns false when PI_EXPERIMENTAL is empty", () => {
+		process.env.PI_EXPERIMENTAL = "";
+
+		expect(areExperimentalFeaturesEnabled()).toBe(false);
+	});
+
+	it("returns true when PI_EXPERIMENTAL is set to 1", () => {
+		process.env.PI_EXPERIMENTAL = "1";
+
+		expect(areExperimentalFeaturesEnabled()).toBe(true);
+	});
+
+	it("returns false when PI_EXPERIMENTAL is set to 0", () => {
+		process.env.PI_EXPERIMENTAL = "0";
+
+		expect(areExperimentalFeaturesEnabled()).toBe(false);
+	});
+
+	it("returns false when PI_EXPERIMENTAL is set to a non-1 value", () => {
+		process.env.PI_EXPERIMENTAL = "true";
+
+		expect(areExperimentalFeaturesEnabled()).toBe(false);
+	});
+});