treehouse

name	treehouse
description	Safely acquire, inspect, and return leased Treehouse workspaces.
allowed-tools	Bash(../../../community/tools/bun.cmd ./scripts/treehouse.ts read:*), Bash(../../../community/tools/bun.cmd ./scripts/treehouse.ts write:*), Bash(../../../tools/bun.cmd ./scripts/treehouse.ts read:*), Bash(../../../tools/bun.cmd ./scripts/treehouse.ts write:*), Bash(./community/tools/bun.cmd ./.claude/skills/treehouse/scripts/treehouse.ts read:*), Bash(./community/tools/bun.cmd ./.claude/skills/treehouse/scripts/treehouse.ts write:*), Bash(./tools/bun.cmd ./.claude/skills/treehouse/scripts/treehouse.ts read:*), Bash(./tools/bun.cmd ./.claude/skills/treehouse/scripts/treehouse.ts write:*)

Treehouse workspace lifecycle

Use this skill when an isolated workspace is required. The CLI wraps only Treehouse's safe leased lifecycle, prepares the acquired workspace at the caller's exact HEAD, records the lease identity inside it, and always guards return with that identity. It never installs or configures Treehouse and does not expose enter, init, update, prune, destroy, or --force.

Run ./scripts/treehouse.ts through the repository-pinned Bun wrapper. From the repository root:

• Ultimate checkout: ./community/tools/bun.cmd ./.claude/skills/treehouse/scripts/treehouse.ts …
• Community checkout: ./tools/bun.cmd ./.claude/skills/treehouse/scripts/treehouse.ts …

From this skill directory, use ../../../community/tools/bun.cmd ./scripts/treehouse.ts … in an Ultimate checkout or ../../../tools/bun.cmd ./scripts/treehouse.ts … in a Community checkout. Output is JSON. Keep read and write invocations separate so approvals remain narrow and reusable.

For Codex, run from this skill directory and request these narrow reusable prefixes when sandbox access requires approval:

• Read-only: ../../../community/tools/bun.cmd ./scripts/treehouse.ts read
• Lease mutations: ../../../community/tools/bun.cmd ./scripts/treehouse.ts write

The write approval permits the wrapper to access Treehouse's pool outside the repository. It does not authorize acquiring or returning a workspace unless the task calls for that lifecycle action.

Inspect the pool

../../../community/tools/bun.cmd ./scripts/treehouse.ts read status

The result includes Treehouse's process list for every workspace. Before returning a workspace, stop every process still using it; the wrapper refuses to return a workspace while Treehouse reports any process.

status is inspection only. An available reusable worktree may have an old detached HEAD; that is expected. Never enter, edit, reset, rebase, or otherwise synchronize a path taken from status. Only write acquire reserves and prepares a workspace for use.

Acquire a workspace

For Codex, first verify that the built-in request_permissions tool is available. If it is not, do not acquire a lease; report that Treehouse cannot be used in the current session. Do not ask the user to change permission settings, restart with --add-dir, or grant access to the Treehouse pool.

../../../community/tools/bun.cmd ./scripts/treehouse.ts write acquire --holder <session-id>

Use the current development or agent session ID as --holder when one is available. If it is omitted, the CLI uses TREEHOUSE_LEASE_HOLDER, then generates a unique agent-<UUID> label. The result contains the workspace path, lease ID, holder, and receipt path. Keep running from the original checkout until the permission step below succeeds.

For Codex, changing a tool's working directory does not add the leased workspace to the session's writable roots. Immediately after acquisition, and before any task edit or write command inside it, use the built-in request_permissions tool to request filesystem write access to exactly the returned workspace path with session scope. After the grant, use that path as the working directory for all subsequent tools. Do not request its parent Treehouse pool, the source checkout, the shared Git directory, or full access, and do not replace the single workspace grant with repeated per-command escalations.

If the grant is denied, do not enter, edit, or run commands in the leased workspace. Immediately run write return --workspace <leased-path> from the original checkout to return the untouched lease. If return fails, retain and report the path, lease ID, and holder as required below; do not ask the user to reconfigure permissions.

Acquisition captures the caller checkout's HEAD, obtains a clean lease, and detaches the leased workspace at that exact commit. The caller's index, working-tree changes, and untracked files are intentionally ignored and are not transferred. The wrapper performs no fetch, rebase, stash, cherry-pick, or file copying. If preparation or verification fails, it returns the new lease when safe; otherwise it retains the lease and receipt and reports their exact identity.

The version-2 receipt is out/treehouse/lease.json inside the acquired workspace and records the captured source_head. out/ is ignored in both repository layouts. Do not edit, move, or copy the receipt between workspaces. Version-1 receipts from existing leases remain returnable.

Return a workspace

Before return, verify that all intended changes are committed or preserved elsewhere and no intended uncommitted or untracked work remains. Stop every process reported for the workspace by read status. Then run from the original checkout or another directory outside the leased workspace, passing the acquired path explicitly:

../../../community/tools/bun.cmd ./scripts/treehouse.ts write return --workspace <leased-path>

The CLI loads the local receipt, verifies its path, lease ID, and holder against live Treehouse status, requires an empty process list, checks Git status, and calls treehouse return with both identity guards. Running outside the leased workspace prevents the wrapper and its parent shell from appearing as workspace processes. The receipt is removed only after Treehouse reports success.

If Git is dirty after the preservation checks, use an interactive TTY and explicitly attest that the work is preserved:

../../../community/tools/bun.cmd ./scripts/treehouse.ts write return --workspace <leased-path> --confirm-preserved

Treehouse will ask Clean and return? [Y/n]; answer Y only after those checks pass. The wrapper refuses a dirty return without the flag or without a TTY, and never substitutes --force.

If return fails, retain the lease and report the path, lease ID, and holder printed in the error. Do not fall back to a raw Git worktree, another clone, or another workspace manager.