The Construct CLI 1.8.12

[1.8.12] - 2026-05-20

Added

• CWD-Derived Container Naming: Each working directory now gets its own container (construct-cli-<sha256[:8]>) instead of a shared singleton. Running agents from multiple terminals with different working directories no longer conflicts with "Container 'construct-cli' is already running." Same directory always hashes to the same container name, preserving attach semantics.

Fixed

• Daemon Killed by sys doctor --fix: cleanupAgentContainer prefix-matched construct-cli-daemon and killed it; recreateDaemonContainer then saw it missing and no-op'd. Daemon is now excluded from session container cleanup.
• Stopped Containers Returned by Network Manager: runningSessionContainers used docker ps -aq (all states), causing spurious UFW rule warnings on stopped containers. Now filters by running state.
• Legacy Singleton Missed by Migration: collectSessionContainers only discovered CWD-hash containers, missing pre-upgrade construct-cli singleton. Now includes exact-match discovery for the legacy name.
• Stale Error Message: sys doctor --fix suggestion referenced old docker rm -f construct-cli instead of prefix-based cleanup.
• Keyring Env Path Hardcoding: readKeyringEnv used os.UserHomeDir() instead of config.GetConfigDir() for the keyring env file path.

Changed

• Container Discovery: All consumers of the static "construct-cli" container name (doctor.go, migration.go, network/manager.go, reset-environment.sh) now discover containers by prefix "construct-cli-" via runtime.ListContainersByPrefix().
• Architecture Docs: Updated ARCHITECTURE-DESIGN.md Sections 4, 9.3, and 11.2.1 for the new naming pattern.

The Construct CLI 1.8.11

[1.8.11] - 2026-05-20

Added

• Antigravity Update Integration: Added agy update integration to the dynamic Topgrade generator (packages.go), topgrade.toml template, and the manual system update fallback script (update-all.sh).

Fixed

• Yolo Configuration for agy: Fixed yolo settings (yolo_all and yolo_agents) to correctly apply the --dangerously-skip-permissions flag when initializing the agy agent.
• Agent Credential Persistence: Added gnome-keyring, libsecret-1-0, and dbus-x11 to the container image, with automatic daemon startup in the entrypoint. Agents (e.g., agy) that rely on the OS keyring for OAuth tokens now persist credentials across container restarts. Previously, every session required a fresh login.
• Keyring Daemon Startup: Fixed gnome-keyring-daemon invocation in the entrypoint. The --start and --unlock flags are mutually exclusive and caused the daemon to silently fail, leaving the keyring locked. Changed to --unlock --components=secrets which both starts the daemon and unlocks the login keyring with a blank password.
• Keyring Env Vars Not Reaching Agents: docker exec runs agents directly (no shell), so .bashrc/.profile are never sourced and GNOME_KEYRING_CONTROL/DBUS_SESSION_BUS_ADDRESS were invisible to agent binaries. agy's keyring auth timed out after 1s, fell back to browser OAuth, and hung. Fixed by having the entrypoint write these vars to ~/.construct-keyring-env, which the Go CLI reads from the host-side bind mount and injects via -e flags on every docker exec.

The Construct CLI 1.8.10

[1.8.10] - 2026-05-20

Fixed

• Agent Credential Persistence: Added gnome-keyring, libsecret-1-0, and dbus-x11 to the container image, with automatic daemon startup in the entrypoint. Agents (e.g., agy) that rely on the OS keyring for OAuth tokens now persist credentials across container restarts. Previously, every session required a fresh login.

[1.8.9] - 2026-05-20

Added

• Antigravity Update Integration: Added agy update integration to the dynamic Topgrade generator (packages.go), topgrade.toml template, and the manual system update fallback script (update-all.sh).

Fixed

• Yolo Configuration for agy: Fixed yolo settings (yolo_all and yolo_agents) to correctly apply the --dangerously-skip-permissions flag when initializing the agy agent.

[1.8.8] - 2026-05-20

Changed

• Replaced Gemini CLI with Antigravity CLI: Replaced gemini agent (Google Gemini CLI, npm-installed) with agy agent (Google Antigravity CLI, curl-installed from https://antigravity.google/cli/install.sh). Binary lands at ~/.local/bin/agy. Removed Gemini-specific clipboard paste wrapper (~220 lines of Python PTY code). Renamed GEMINI_API_KEY to ANTIGRAVITY_API_KEY throughout source, templates, and docs. Updated agent registration, memory paths, constants, env passthrough, runtime candidates, wayland/yolo flags, help text, aliases, verification loops, and all documentation.

[1.8.7] - 2026-05-15

Fixed

• Yolo Mode Ignored on Cold-Start: Config values (yolo_all, yolo_agents) from config.toml were not applied when running agents via the cold-start (non-daemon) path. Root cause: Execute() applied yolo flags to a local variable, but runNewContainer() discarded its args parameter (_) and read e.args directly from the struct. The daemon path worked because it passed yolo-applied args directly. Fixed by writing yolo results back to e.args and removing the dead parameter from runNewContainer().

[1.8.6] - 2026-05-14

Fixed

• Global AGENTS.md Symlinks Leaked onto Host: Removed creation of AGENTS.md, CLAUDE.md, and GEMINI.md symlinks in /workspaces/ and /projects/. These directories are host bind mounts, so symlinks pointing to the container-internal /home/construct/AGENTS.md leaked onto the host filesystem as dangling links. Symlink aliases are now created only inside /home/construct/ (container-internal). Existing dangling symlinks on the host must be cleaned up manually.

[1.8.5] - 2026-05-12

Fixed

• AGENTS.md Symlink Scope: Fixed symlinks being created at every directory level (including project subdirectories), which overwrote pre-existing AGENTS.md files. Symlinks are now created only at /workspaces/, /workspaces/<hash>/, and /projects/. Pre-existing real files are never overwritten. Now also creates CLAUDE.md and GEMINI.md symlinks alongside AGENTS.md, all pointing to the global rules file.

[1.8.4] - 2026-05-11

Added

• Global AGENTS.md Symlinks: Automatically creates symlinks to the global AGENTS.md rules file in common mount points (/workspaces/, /projects/) and their subdirectories. This ensures agents can easily discover global instructions regardless of the project's mount path or random daemon hash.

[1.8.3] - 2026-05-09

Fixed

• ARM64 Setup & agent-browser: Fixed agent-browser installation failure on ARM64 Linux by implementing an automatic wrapper that uses the system Chromium (/usr/bin/chromium).
• Resilient Package Installation: Added failure-safe command execution (cmd || echo ...) in install_user_packages.sh to prevent a single tool failure from aborting the entire setup.
• Sudo Detection: Improved SUDO_AVAILABLE check to use sudo -n apt-get --version, resolving issues in restricted sudoers environments where true was not permitted.
• Multimodal Clipboard Regression: Resolved image pasting failures in Gemini and Codex agents.
  • macOS Networking: Fixed 127.0.0.1 hardcoding in the clipboard server; now correctly uses host.docker.internal (or configured clipboard_host), making the host clipboard reachable from the container.
  • Ghostty / Bracketed Paste Support: Added PTY interception for \x1b[200~ sequences. PTY wrappers now consume bracketed paste content and inject image paths directly, bypassing terminal protocol mismatches.
  • Daemon Patching: Restored runAgentPatchInDaemon logic to ensure shims, wrappers, and Xvfb are correctly initialized in persistent daemon containers.
  • Headless X11 (Xvfb): Moved Xvfb startup to the agent-patch script to ensure a valid DISPLAY is always available for agents that expect a real display.
  • Gemini @-prefix: Ensured Gemini uses the required @path injection format while Codex uses raw paths.
• Agent Update Hardening: Added defensive command -v checks for Claude and Pi update commands in Topgrade configuration, preventing errors in environments where these agents are not installed.

Changed

• Official Goose CLI Installer: Switched to the official Goose installation script (github.com/aaif-goose/goose) for more reliable setup.
• Updated OpenCode Installer: Updated the OpenCode post-install command to use the canonical curl -fsSL https://opencode.ai/install | bash.
• Pi Update Integration: Integrated pi update into the primary Topgrade update path to ensure Pi and its internal packages are kept current during ct sys update.
• Clean Brew Installation Logs: Optimized the Homebrew installation script to check for existing packages before running brew install, replacing noisy "already installed" warnings with clean confirmation messages.

Optimized

• Fast Agent Startup (Patch Marker): Implemented a versioned marker-based guard (~/.construct_patched) to skip redundant agent clipboard patching on startup. This significantly reduces latency when entering a shell or launching an agent in a warm daemon container. Patching is now only re-triggered after Construct version changes or package installations.

[1.8.2] - 2026-05-09

Fixed

• Daemon shell with no args: execViaDaemon now defaults to the configured shell (sandbox.shell or /bin/bash) when invoked without arguments, matching the existing behavior of execInRunningContainer. Previously, ct sys shell passed an empty command to docker exec, causing "requires at least 2 arguments" error.

[1.8.1] - 2026-05-09

Fixed

• Root exec in daemon containers: resolveExecUserForRunningContainer() now returns "construct" on all code paths instead of "". Previously, docker exec -it into the daemon ran agents as root (since USER construct is commented out in the Dockerfile), causing Claude CLI to reject --dangerously-skip-permissions. Added uid==0 guard and UsesUserNamespaceRemap() check.
• Pre-existing test failure on uid=0 CI: TestAppendExecUserRunFlags now correctly handles root environments by expecting no --user flag when uid=0.
• Missing daemon launch messages: Restored "Running in Construct daemon: [args]", "Entering Construct daemon shell...", "✓ Started SSH Agent proxy (daemon)", and exit code 126/127 PATH hints that were lost in the v1.8.0 refactor.

Changed

• Claude install moved to packages.toml: Claude Code installation moved from hardcoded packages.go to [post_install] section in packages.toml, consistent with droid/opencode pattern.
• Pi self-update in update routine: Added pi update to both update-all.sh manual fallback and topgrade [commands] config.

Removed

• Dead code cleanup: Removed unused containerHasUIDEntryFn variable, dead execUserForAgentExec function (never called from production), and stale test mocks that referenced removed behavior.

[1.8.0] - 2026-05-08

Changed

• Runtime Engine Extraction: Extracted ~1000 lines of monolithic container orchestration from internal/agent/runner.go into a dedicated RuntimeEngine in new internal/agent/engine.go. runner.go now delegates to engine.Prepare() and engine.Execute(), centralizing daemon detection, clipboard server, SSH bridge, login forwarding, environment assembly, and container state handling.
• Security Session Interface: Introduced a new Session interface in internal/security/session_deep.go with noOpSession (disabled) and secureSession (active) implementations. Replaces direct SessionManager coupling throughout the codebase with a clean, testable abstraction.
• SecretShield Deep Module: Created internal/security/shield.go as a deep module encapsulating secret detection and redaction into a single atomic Protect() operation. integration.go now delegates scanning to SecretShield instead of orchestrating Scanner directly.
• Runner Integration Refactor: internal/security/runner_integration.go completely rewritten around the Session interface. Uses the new security.Open() factory and delegates env masking to sess.MaskEnv(). Eliminates redundant EnvMasker instantiation at every call site.
• Scanner JSON Serialization: Replaced hand-rolled string-buffer JSON generation in internal/security/scanner.go with proper encoding/json MarshalIndent/Unmarshal for manifest and redaction index I/O.
• RiPGrep Path Resolution: Changed hardcoded /usr/bin/rg stat to exec.LookPath("rg") for cross-distro compatibility.
• Session Manager Cleanup Removal: Removed Manager.Cleanup() and isProcessAlive orphan-reaping logic from internal/security/session.go. Session lifecycle is now managed explicitly through the Session interface.
• **Workspace ...

The Construct CLI 1.8.9

[1.8.9] - 2026-05-20

Added

• Antigravity Update Integration: Added agy update integration to the dynamic Topgrade generator (packages.go), topgrade.toml template, and the manual system update fallback script (update-all.sh).

Fixed

• Yolo Configuration for agy: Fixed yolo settings (yolo_all and yolo_agents) to correctly apply the --dangerously-skip-permissions flag when initializing the agy agent.

[1.8.8] - 2026-05-20

Changed

• Replaced Gemini CLI with Antigravity CLI: Replaced gemini agent (Google Gemini CLI, npm-installed) with agy agent (Google Antigravity CLI, curl-installed from https://antigravity.google/cli/install.sh). Binary lands at ~/.local/bin/agy. Removed Gemini-specific clipboard paste wrapper (~220 lines of Python PTY code). Renamed GEMINI_API_KEY to ANTIGRAVITY_API_KEY throughout source, templates, and docs. Updated agent registration, memory paths, constants, env passthrough, runtime candidates, wayland/yolo flags, help text, aliases, verification loops, and all documentation.

[1.8.7] - 2026-05-15

Fixed

• Yolo Mode Ignored on Cold-Start: Config values (yolo_all, yolo_agents) from config.toml were not applied when running agents via the cold-start (non-daemon) path. Root cause: Execute() applied yolo flags to a local variable, but runNewContainer() discarded its args parameter (_) and read e.args directly from the struct. The daemon path worked because it passed yolo-applied args directly. Fixed by writing yolo results back to e.args and removing the dead parameter from runNewContainer().

[1.8.6] - 2026-05-14

Fixed

• Global AGENTS.md Symlinks Leaked onto Host: Removed creation of AGENTS.md, CLAUDE.md, and GEMINI.md symlinks in /workspaces/ and /projects/. These directories are host bind mounts, so symlinks pointing to the container-internal /home/construct/AGENTS.md leaked onto the host filesystem as dangling links. Symlink aliases are now created only inside /home/construct/ (container-internal). Existing dangling symlinks on the host must be cleaned up manually.

[1.8.5] - 2026-05-12

Fixed

• AGENTS.md Symlink Scope: Fixed symlinks being created at every directory level (including project subdirectories), which overwrote pre-existing AGENTS.md files. Symlinks are now created only at /workspaces/, /workspaces/<hash>/, and /projects/. Pre-existing real files are never overwritten. Now also creates CLAUDE.md and GEMINI.md symlinks alongside AGENTS.md, all pointing to the global rules file.

[1.8.4] - 2026-05-11

Added

• Global AGENTS.md Symlinks: Automatically creates symlinks to the global AGENTS.md rules file in common mount points (/workspaces/, /projects/) and their subdirectories. This ensures agents can easily discover global instructions regardless of the project's mount path or random daemon hash.

[1.8.3] - 2026-05-09

Fixed

• ARM64 Setup & agent-browser: Fixed agent-browser installation failure on ARM64 Linux by implementing an automatic wrapper that uses the system Chromium (/usr/bin/chromium).
• Resilient Package Installation: Added failure-safe command execution (cmd || echo ...) in install_user_packages.sh to prevent a single tool failure from aborting the entire setup.
• Sudo Detection: Improved SUDO_AVAILABLE check to use sudo -n apt-get --version, resolving issues in restricted sudoers environments where true was not permitted.
• Multimodal Clipboard Regression: Resolved image pasting failures in Gemini and Codex agents.
  • macOS Networking: Fixed 127.0.0.1 hardcoding in the clipboard server; now correctly uses host.docker.internal (or configured clipboard_host), making the host clipboard reachable from the container.
  • Ghostty / Bracketed Paste Support: Added PTY interception for \x1b[200~ sequences. PTY wrappers now consume bracketed paste content and inject image paths directly, bypassing terminal protocol mismatches.
  • Daemon Patching: Restored runAgentPatchInDaemon logic to ensure shims, wrappers, and Xvfb are correctly initialized in persistent daemon containers.
  • Headless X11 (Xvfb): Moved Xvfb startup to the agent-patch script to ensure a valid DISPLAY is always available for agents that expect a real display.
  • Gemini @-prefix: Ensured Gemini uses the required @path injection format while Codex uses raw paths.
• Agent Update Hardening: Added defensive command -v checks for Claude and Pi update commands in Topgrade configuration, preventing errors in environments where these agents are not installed.

Changed

• Official Goose CLI Installer: Switched to the official Goose installation script (github.com/aaif-goose/goose) for more reliable setup.
• Updated OpenCode Installer: Updated the OpenCode post-install command to use the canonical curl -fsSL https://opencode.ai/install | bash.
• Pi Update Integration: Integrated pi update into the primary Topgrade update path to ensure Pi and its internal packages are kept current during ct sys update.
• Clean Brew Installation Logs: Optimized the Homebrew installation script to check for existing packages before running brew install, replacing noisy "already installed" warnings with clean confirmation messages.

Optimized

• Fast Agent Startup (Patch Marker): Implemented a versioned marker-based guard (~/.construct_patched) to skip redundant agent clipboard patching on startup. This significantly reduces latency when entering a shell or launching an agent in a warm daemon container. Patching is now only re-triggered after Construct version changes or package installations.

[1.8.2] - 2026-05-09

Fixed

• Daemon shell with no args: execViaDaemon now defaults to the configured shell (sandbox.shell or /bin/bash) when invoked without arguments, matching the existing behavior of execInRunningContainer. Previously, ct sys shell passed an empty command to docker exec, causing "requires at least 2 arguments" error.

[1.8.1] - 2026-05-09

Fixed

• Root exec in daemon containers: resolveExecUserForRunningContainer() now returns "construct" on all code paths instead of "". Previously, docker exec -it into the daemon ran agents as root (since USER construct is commented out in the Dockerfile), causing Claude CLI to reject --dangerously-skip-permissions. Added uid==0 guard and UsesUserNamespaceRemap() check.
• Pre-existing test failure on uid=0 CI: TestAppendExecUserRunFlags now correctly handles root environments by expecting no --user flag when uid=0.
• Missing daemon launch messages: Restored "Running in Construct daemon: [args]", "Entering Construct daemon shell...", "✓ Started SSH Agent proxy (daemon)", and exit code 126/127 PATH hints that were lost in the v1.8.0 refactor.

Changed

• Claude install moved to packages.toml: Claude Code installation moved from hardcoded packages.go to [post_install] section in packages.toml, consistent with droid/opencode pattern.
• Pi self-update in update routine: Added pi update to both update-all.sh manual fallback and topgrade [commands] config.

Removed

• Dead code cleanup: Removed unused containerHasUIDEntryFn variable, dead execUserForAgentExec function (never called from production), and stale test mocks that referenced removed behavior.

[1.8.0] - 2026-05-08

Changed

• Runtime Engine Extraction: Extracted ~1000 lines of monolithic container orchestration from internal/agent/runner.go into a dedicated RuntimeEngine in new internal/agent/engine.go. runner.go now delegates to engine.Prepare() and engine.Execute(), centralizing daemon detection, clipboard server, SSH bridge, login forwarding, environment assembly, and container state handling.
• Security Session Interface: Introduced a new Session interface in internal/security/session_deep.go with noOpSession (disabled) and secureSession (active) implementations. Replaces direct SessionManager coupling throughout the codebase with a clean, testable abstraction.
• SecretShield Deep Module: Created internal/security/shield.go as a deep module encapsulating secret detection and redaction into a single atomic Protect() operation. integration.go now delegates scanning to SecretShield instead of orchestrating Scanner directly.
• Runner Integration Refactor: internal/security/runner_integration.go completely rewritten around the Session interface. Uses the new security.Open() factory and delegates env masking to sess.MaskEnv(). Eliminates redundant EnvMasker instantiation at every call site.
• Scanner JSON Serialization: Replaced hand-rolled string-buffer JSON generation in internal/security/scanner.go with proper encoding/json MarshalIndent/Unmarshal for manifest and redaction index I/O.
• RiPGrep Path Resolution: Changed hardcoded /usr/bin/rg stat to exec.LookPath("rg") for cross-distro compatibility.
• Session Manager Cleanup Removal: Removed Manager.Cleanup() and isProcessAlive orphan-reaping logic from internal/security/session.go. Session lifecycle is now managed explicitly through the Session interface.
• Workspace Type Override: Added CONSTRUCT_SECURITY_WORKSPACE_TYPE environment variable and WorkspaceTypeNone for testability. DetectWorkspaceType() now respects the override.
• OverlayFS Mount Fix: Corrected overlayfs mount options to use lowerdir=<lower>,upperdir=<upper>,workdir=<work> instead of the erroneous lowerdir=<lower>:<upper>,upperdir=<upper>,workdir=<work> that duplicated the up...

The Construct CLI 1.8.7

[1.8.7] - 2026-05-15

Fixed

• Yolo Mode Ignored on Cold-Start: Config values (yolo_all, yolo_agents) from config.toml were not applied when running agents via the cold-start (non-daemon) path. Root cause: Execute() applied yolo flags to a local variable, but runNewContainer() discarded its args parameter (_) and read e.args directly from the struct. The daemon path worked because it passed yolo-applied args directly. Fixed by writing yolo results back to e.args and removing the dead parameter from runNewContainer().

[1.8.6] - 2026-05-14

Fixed

• Global AGENTS.md Symlinks Leaked onto Host: Removed creation of AGENTS.md, CLAUDE.md, and GEMINI.md symlinks in /workspaces/ and /projects/. These directories are host bind mounts, so symlinks pointing to the container-internal /home/construct/AGENTS.md leaked onto the host filesystem as dangling links. Symlink aliases are now created only inside /home/construct/ (container-internal). Existing dangling symlinks on the host must be cleaned up manually.

[1.8.5] - 2026-05-12

Fixed

• AGENTS.md Symlink Scope: Fixed symlinks being created at every directory level (including project subdirectories), which overwrote pre-existing AGENTS.md files. Symlinks are now created only at /workspaces/, /workspaces/<hash>/, and /projects/. Pre-existing real files are never overwritten. Now also creates CLAUDE.md and GEMINI.md symlinks alongside AGENTS.md, all pointing to the global rules file.

[1.8.4] - 2026-05-11

Added

• Global AGENTS.md Symlinks: Automatically creates symlinks to the global AGENTS.md rules file in common mount points (/workspaces/, /projects/) and their subdirectories. This ensures agents can easily discover global instructions regardless of the project's mount path or random daemon hash.

[1.8.3] - 2026-05-09

Fixed

• ARM64 Setup & agent-browser: Fixed agent-browser installation failure on ARM64 Linux by implementing an automatic wrapper that uses the system Chromium (/usr/bin/chromium).
• Resilient Package Installation: Added failure-safe command execution (cmd || echo ...) in install_user_packages.sh to prevent a single tool failure from aborting the entire setup.
• Sudo Detection: Improved SUDO_AVAILABLE check to use sudo -n apt-get --version, resolving issues in restricted sudoers environments where true was not permitted.
• Multimodal Clipboard Regression: Resolved image pasting failures in Gemini and Codex agents.
  • macOS Networking: Fixed 127.0.0.1 hardcoding in the clipboard server; now correctly uses host.docker.internal (or configured clipboard_host), making the host clipboard reachable from the container.
  • Ghostty / Bracketed Paste Support: Added PTY interception for \x1b[200~ sequences. PTY wrappers now consume bracketed paste content and inject image paths directly, bypassing terminal protocol mismatches.
  • Daemon Patching: Restored runAgentPatchInDaemon logic to ensure shims, wrappers, and Xvfb are correctly initialized in persistent daemon containers.
  • Headless X11 (Xvfb): Moved Xvfb startup to the agent-patch script to ensure a valid DISPLAY is always available for agents that expect a real display.
  • Gemini @-prefix: Ensured Gemini uses the required @path injection format while Codex uses raw paths.
• Agent Update Hardening: Added defensive command -v checks for Claude and Pi update commands in Topgrade configuration, preventing errors in environments where these agents are not installed.

Changed

• Official Goose CLI Installer: Switched to the official Goose installation script (github.com/aaif-goose/goose) for more reliable setup.
• Updated OpenCode Installer: Updated the OpenCode post-install command to use the canonical curl -fsSL https://opencode.ai/install | bash.
• Pi Update Integration: Integrated pi update into the primary Topgrade update path to ensure Pi and its internal packages are kept current during ct sys update.
• Clean Brew Installation Logs: Optimized the Homebrew installation script to check for existing packages before running brew install, replacing noisy "already installed" warnings with clean confirmation messages.

Optimized

• Fast Agent Startup (Patch Marker): Implemented a versioned marker-based guard (~/.construct_patched) to skip redundant agent clipboard patching on startup. This significantly reduces latency when entering a shell or launching an agent in a warm daemon container. Patching is now only re-triggered after Construct version changes or package installations.

[1.8.2] - 2026-05-09

Fixed

• Daemon shell with no args: execViaDaemon now defaults to the configured shell (sandbox.shell or /bin/bash) when invoked without arguments, matching the existing behavior of execInRunningContainer. Previously, ct sys shell passed an empty command to docker exec, causing "requires at least 2 arguments" error.

[1.8.1] - 2026-05-09

Fixed

• Root exec in daemon containers: resolveExecUserForRunningContainer() now returns "construct" on all code paths instead of "". Previously, docker exec -it into the daemon ran agents as root (since USER construct is commented out in the Dockerfile), causing Claude CLI to reject --dangerously-skip-permissions. Added uid==0 guard and UsesUserNamespaceRemap() check.
• Pre-existing test failure on uid=0 CI: TestAppendExecUserRunFlags now correctly handles root environments by expecting no --user flag when uid=0.
• Missing daemon launch messages: Restored "Running in Construct daemon: [args]", "Entering Construct daemon shell...", "✓ Started SSH Agent proxy (daemon)", and exit code 126/127 PATH hints that were lost in the v1.8.0 refactor.

Changed

• Claude install moved to packages.toml: Claude Code installation moved from hardcoded packages.go to [post_install] section in packages.toml, consistent with droid/opencode pattern.
• Pi self-update in update routine: Added pi update to both update-all.sh manual fallback and topgrade [commands] config.

Removed

• Dead code cleanup: Removed unused containerHasUIDEntryFn variable, dead execUserForAgentExec function (never called from production), and stale test mocks that referenced removed behavior.

[1.8.0] - 2026-05-08

Changed

• Runtime Engine Extraction: Extracted ~1000 lines of monolithic container orchestration from internal/agent/runner.go into a dedicated RuntimeEngine in new internal/agent/engine.go. runner.go now delegates to engine.Prepare() and engine.Execute(), centralizing daemon detection, clipboard server, SSH bridge, login forwarding, environment assembly, and container state handling.
• Security Session Interface: Introduced a new Session interface in internal/security/session_deep.go with noOpSession (disabled) and secureSession (active) implementations. Replaces direct SessionManager coupling throughout the codebase with a clean, testable abstraction.
• SecretShield Deep Module: Created internal/security/shield.go as a deep module encapsulating secret detection and redaction into a single atomic Protect() operation. integration.go now delegates scanning to SecretShield instead of orchestrating Scanner directly.
• Runner Integration Refactor: internal/security/runner_integration.go completely rewritten around the Session interface. Uses the new security.Open() factory and delegates env masking to sess.MaskEnv(). Eliminates redundant EnvMasker instantiation at every call site.
• Scanner JSON Serialization: Replaced hand-rolled string-buffer JSON generation in internal/security/scanner.go with proper encoding/json MarshalIndent/Unmarshal for manifest and redaction index I/O.
• RiPGrep Path Resolution: Changed hardcoded /usr/bin/rg stat to exec.LookPath("rg") for cross-distro compatibility.
• Session Manager Cleanup Removal: Removed Manager.Cleanup() and isProcessAlive orphan-reaping logic from internal/security/session.go. Session lifecycle is now managed explicitly through the Session interface.
• Workspace Type Override: Added CONSTRUCT_SECURITY_WORKSPACE_TYPE environment variable and WorkspaceTypeNone for testability. DetectWorkspaceType() now respects the override.
• OverlayFS Mount Fix: Corrected overlayfs mount options to use lowerdir=<lower>,upperdir=<upper>,workdir=<work> instead of the erroneous lowerdir=<lower>:<upper>,upperdir=<upper>,workdir=<work> that duplicated the upper layer in the lower stack.
• Setup PATH Construction: runSetup now constructs PATH and CONSTRUCT_PATH directly via env.BuildConstructPath() instead of the removed applyConstructPath() helper.

Added

• Clipboard Server Stop: Added Stop() method to internal/clipboard/server.go for clean listener shutdown.
• Security Session Tests: Added internal/security/session_test.go with regression coverage for both noOpSession (disabled) and secureSession (enabled with CONSTRUCT_SECURITY_WORKSPACE_TYPE=none) deep interface behavior.

Fixed

• Nil Status Guards: Added nil-pointer checks in internal/security/integration.go before calling sm.status.IsEnabled().
• CI Lint Toolchain Pin: Bumped golangci-lint pin from v2.11.4 to v2.12.2 in build and release workflows; aligned local Makefile CI pin to 2.12.2.

Removed

• ~29 Helper Functions from runner.go: Removed collectForwardedEnv, buildRunFlags, shouldEnableLoginForward, applyYoloArgs, applyConstructPath, execUserForAgentExec, appendExecUserRunFlags, resolveExecUserForRunningContainer, `shoul...

The Construct CLI 1.8.6

[1.8.6] - 2026-05-14

Fixed

• Global AGENTS.md Symlinks Leaked onto Host: Removed creation of AGENTS.md, CLAUDE.md, and GEMINI.md symlinks in /workspaces/ and /projects/. These directories are host bind mounts, so symlinks pointing to the container-internal /home/construct/AGENTS.md leaked onto the host filesystem as dangling links. Symlink aliases are now created only inside /home/construct/ (container-internal). Existing dangling symlinks on the host must be cleaned up manually.

[1.8.5] - 2026-05-12

Fixed

• AGENTS.md Symlink Scope: Fixed symlinks being created at every directory level (including project subdirectories), which overwrote pre-existing AGENTS.md files. Symlinks are now created only at /workspaces/, /workspaces/<hash>/, and /projects/. Pre-existing real files are never overwritten. Now also creates CLAUDE.md and GEMINI.md symlinks alongside AGENTS.md, all pointing to the global rules file.

[1.8.4] - 2026-05-11

Added

• Global AGENTS.md Symlinks: Automatically creates symlinks to the global AGENTS.md rules file in common mount points (/workspaces/, /projects/) and their subdirectories. This ensures agents can easily discover global instructions regardless of the project's mount path or random daemon hash.

[1.8.3] - 2026-05-09

Fixed

• ARM64 Setup & agent-browser: Fixed agent-browser installation failure on ARM64 Linux by implementing an automatic wrapper that uses the system Chromium (/usr/bin/chromium).
• Resilient Package Installation: Added failure-safe command execution (cmd || echo ...) in install_user_packages.sh to prevent a single tool failure from aborting the entire setup.
• Sudo Detection: Improved SUDO_AVAILABLE check to use sudo -n apt-get --version, resolving issues in restricted sudoers environments where true was not permitted.
• Multimodal Clipboard Regression: Resolved image pasting failures in Gemini and Codex agents.
  • macOS Networking: Fixed 127.0.0.1 hardcoding in the clipboard server; now correctly uses host.docker.internal (or configured clipboard_host), making the host clipboard reachable from the container.
  • Ghostty / Bracketed Paste Support: Added PTY interception for \x1b[200~ sequences. PTY wrappers now consume bracketed paste content and inject image paths directly, bypassing terminal protocol mismatches.
  • Daemon Patching: Restored runAgentPatchInDaemon logic to ensure shims, wrappers, and Xvfb are correctly initialized in persistent daemon containers.
  • Headless X11 (Xvfb): Moved Xvfb startup to the agent-patch script to ensure a valid DISPLAY is always available for agents that expect a real display.
  • Gemini @-prefix: Ensured Gemini uses the required @path injection format while Codex uses raw paths.
• Agent Update Hardening: Added defensive command -v checks for Claude and Pi update commands in Topgrade configuration, preventing errors in environments where these agents are not installed.

Changed

• Official Goose CLI Installer: Switched to the official Goose installation script (github.com/aaif-goose/goose) for more reliable setup.
• Updated OpenCode Installer: Updated the OpenCode post-install command to use the canonical curl -fsSL https://opencode.ai/install | bash.
• Pi Update Integration: Integrated pi update into the primary Topgrade update path to ensure Pi and its internal packages are kept current during ct sys update.
• Clean Brew Installation Logs: Optimized the Homebrew installation script to check for existing packages before running brew install, replacing noisy "already installed" warnings with clean confirmation messages.

Optimized

• Fast Agent Startup (Patch Marker): Implemented a versioned marker-based guard (~/.construct_patched) to skip redundant agent clipboard patching on startup. This significantly reduces latency when entering a shell or launching an agent in a warm daemon container. Patching is now only re-triggered after Construct version changes or package installations.

[1.8.2] - 2026-05-09

Fixed

• Daemon shell with no args: execViaDaemon now defaults to the configured shell (sandbox.shell or /bin/bash) when invoked without arguments, matching the existing behavior of execInRunningContainer. Previously, ct sys shell passed an empty command to docker exec, causing "requires at least 2 arguments" error.

[1.8.1] - 2026-05-09

Fixed

• Root exec in daemon containers: resolveExecUserForRunningContainer() now returns "construct" on all code paths instead of "". Previously, docker exec -it into the daemon ran agents as root (since USER construct is commented out in the Dockerfile), causing Claude CLI to reject --dangerously-skip-permissions. Added uid==0 guard and UsesUserNamespaceRemap() check.
• Pre-existing test failure on uid=0 CI: TestAppendExecUserRunFlags now correctly handles root environments by expecting no --user flag when uid=0.
• Missing daemon launch messages: Restored "Running in Construct daemon: [args]", "Entering Construct daemon shell...", "✓ Started SSH Agent proxy (daemon)", and exit code 126/127 PATH hints that were lost in the v1.8.0 refactor.

Changed

• Claude install moved to packages.toml: Claude Code installation moved from hardcoded packages.go to [post_install] section in packages.toml, consistent with droid/opencode pattern.
• Pi self-update in update routine: Added pi update to both update-all.sh manual fallback and topgrade [commands] config.

Removed

• Dead code cleanup: Removed unused containerHasUIDEntryFn variable, dead execUserForAgentExec function (never called from production), and stale test mocks that referenced removed behavior.

[1.8.0] - 2026-05-08

Changed

• Runtime Engine Extraction: Extracted ~1000 lines of monolithic container orchestration from internal/agent/runner.go into a dedicated RuntimeEngine in new internal/agent/engine.go. runner.go now delegates to engine.Prepare() and engine.Execute(), centralizing daemon detection, clipboard server, SSH bridge, login forwarding, environment assembly, and container state handling.
• Security Session Interface: Introduced a new Session interface in internal/security/session_deep.go with noOpSession (disabled) and secureSession (active) implementations. Replaces direct SessionManager coupling throughout the codebase with a clean, testable abstraction.
• SecretShield Deep Module: Created internal/security/shield.go as a deep module encapsulating secret detection and redaction into a single atomic Protect() operation. integration.go now delegates scanning to SecretShield instead of orchestrating Scanner directly.
• Runner Integration Refactor: internal/security/runner_integration.go completely rewritten around the Session interface. Uses the new security.Open() factory and delegates env masking to sess.MaskEnv(). Eliminates redundant EnvMasker instantiation at every call site.
• Scanner JSON Serialization: Replaced hand-rolled string-buffer JSON generation in internal/security/scanner.go with proper encoding/json MarshalIndent/Unmarshal for manifest and redaction index I/O.
• RiPGrep Path Resolution: Changed hardcoded /usr/bin/rg stat to exec.LookPath("rg") for cross-distro compatibility.
• Session Manager Cleanup Removal: Removed Manager.Cleanup() and isProcessAlive orphan-reaping logic from internal/security/session.go. Session lifecycle is now managed explicitly through the Session interface.
• Workspace Type Override: Added CONSTRUCT_SECURITY_WORKSPACE_TYPE environment variable and WorkspaceTypeNone for testability. DetectWorkspaceType() now respects the override.
• OverlayFS Mount Fix: Corrected overlayfs mount options to use lowerdir=<lower>,upperdir=<upper>,workdir=<work> instead of the erroneous lowerdir=<lower>:<upper>,upperdir=<upper>,workdir=<work> that duplicated the upper layer in the lower stack.
• Setup PATH Construction: runSetup now constructs PATH and CONSTRUCT_PATH directly via env.BuildConstructPath() instead of the removed applyConstructPath() helper.

Added

• Clipboard Server Stop: Added Stop() method to internal/clipboard/server.go for clean listener shutdown.
• Security Session Tests: Added internal/security/session_test.go with regression coverage for both noOpSession (disabled) and secureSession (enabled with CONSTRUCT_SECURITY_WORKSPACE_TYPE=none) deep interface behavior.

Fixed

• Nil Status Guards: Added nil-pointer checks in internal/security/integration.go before calling sm.status.IsEnabled().
• CI Lint Toolchain Pin: Bumped golangci-lint pin from v2.11.4 to v2.12.2 in build and release workflows; aligned local Makefile CI pin to 2.12.2.

Removed

• ~29 Helper Functions from runner.go: Removed collectForwardedEnv, buildRunFlags, shouldEnableLoginForward, applyYoloArgs, applyConstructPath, execUserForAgentExec, appendExecUserRunFlags, resolveExecUserForRunningContainer, shouldEnableYolo, yoloFlagForAgent, readLoginBridgePorts, parsePorts, formatPorts, mapDaemonWorkdir, warnDaemonMountFallback, getEffectiveCwd, execViaDaemon, runAgentPatchInDaemon, buildDaemonExecEnv, execInRunningContainer, startDaemonSSHBridge, ensureDaemonSSHProxy, waitForDaemonSSHProxy, checkDaemonSSHProxy, startDaemonBackground, waitForDaemon, ensureAgentRuntimeDirs, appendAgentSpecificRunFlags, appendAgentSpecificDaemonEnv, and appendAgentSpecificExecEnv. All behavior preserved in RuntimeEngine.

---

<!-...

The Construct CLI 1.8.5

[1.8.5] - 2026-05-12

Fixed

• AGENTS.md Symlink Scope: Fixed symlinks being created at every directory level (including project subdirectories), which overwrote pre-existing AGENTS.md files. Symlinks are now created only at /workspaces/, /workspaces/<hash>/, and /projects/. Pre-existing real files are never overwritten. Now also creates CLAUDE.md and GEMINI.md symlinks alongside AGENTS.md, all pointing to the global rules file.

[1.8.4] - 2026-05-11

Added

• Global AGENTS.md Symlinks: Automatically creates symlinks to the global AGENTS.md rules file in common mount points (/workspaces/, /projects/) and their subdirectories. This ensures agents can easily discover global instructions regardless of the project's mount path or random daemon hash.

[1.8.3] - 2026-05-09

Fixed

• ARM64 Setup & agent-browser: Fixed agent-browser installation failure on ARM64 Linux by implementing an automatic wrapper that uses the system Chromium (/usr/bin/chromium).
• Resilient Package Installation: Added failure-safe command execution (cmd || echo ...) in install_user_packages.sh to prevent a single tool failure from aborting the entire setup.
• Sudo Detection: Improved SUDO_AVAILABLE check to use sudo -n apt-get --version, resolving issues in restricted sudoers environments where true was not permitted.
• Multimodal Clipboard Regression: Resolved image pasting failures in Gemini and Codex agents.
  • macOS Networking: Fixed 127.0.0.1 hardcoding in the clipboard server; now correctly uses host.docker.internal (or configured clipboard_host), making the host clipboard reachable from the container.
  • Ghostty / Bracketed Paste Support: Added PTY interception for \x1b[200~ sequences. PTY wrappers now consume bracketed paste content and inject image paths directly, bypassing terminal protocol mismatches.
  • Daemon Patching: Restored runAgentPatchInDaemon logic to ensure shims, wrappers, and Xvfb are correctly initialized in persistent daemon containers.
  • Headless X11 (Xvfb): Moved Xvfb startup to the agent-patch script to ensure a valid DISPLAY is always available for agents that expect a real display.
  • Gemini @-prefix: Ensured Gemini uses the required @path injection format while Codex uses raw paths.
• Agent Update Hardening: Added defensive command -v checks for Claude and Pi update commands in Topgrade configuration, preventing errors in environments where these agents are not installed.

Changed

• Official Goose CLI Installer: Switched to the official Goose installation script (github.com/aaif-goose/goose) for more reliable setup.
• Updated OpenCode Installer: Updated the OpenCode post-install command to use the canonical curl -fsSL https://opencode.ai/install | bash.
• Pi Update Integration: Integrated pi update into the primary Topgrade update path to ensure Pi and its internal packages are kept current during ct sys update.
• Clean Brew Installation Logs: Optimized the Homebrew installation script to check for existing packages before running brew install, replacing noisy "already installed" warnings with clean confirmation messages.

Optimized

• Fast Agent Startup (Patch Marker): Implemented a versioned marker-based guard (~/.construct_patched) to skip redundant agent clipboard patching on startup. This significantly reduces latency when entering a shell or launching an agent in a warm daemon container. Patching is now only re-triggered after Construct version changes or package installations.

[1.8.2] - 2026-05-09

Fixed

• Daemon shell with no args: execViaDaemon now defaults to the configured shell (sandbox.shell or /bin/bash) when invoked without arguments, matching the existing behavior of execInRunningContainer. Previously, ct sys shell passed an empty command to docker exec, causing "requires at least 2 arguments" error.

[1.8.1] - 2026-05-09

Fixed

• Root exec in daemon containers: resolveExecUserForRunningContainer() now returns "construct" on all code paths instead of "". Previously, docker exec -it into the daemon ran agents as root (since USER construct is commented out in the Dockerfile), causing Claude CLI to reject --dangerously-skip-permissions. Added uid==0 guard and UsesUserNamespaceRemap() check.
• Pre-existing test failure on uid=0 CI: TestAppendExecUserRunFlags now correctly handles root environments by expecting no --user flag when uid=0.
• Missing daemon launch messages: Restored "Running in Construct daemon: [args]", "Entering Construct daemon shell...", "✓ Started SSH Agent proxy (daemon)", and exit code 126/127 PATH hints that were lost in the v1.8.0 refactor.

Changed

• Claude install moved to packages.toml: Claude Code installation moved from hardcoded packages.go to [post_install] section in packages.toml, consistent with droid/opencode pattern.
• Pi self-update in update routine: Added pi update to both update-all.sh manual fallback and topgrade [commands] config.

Removed

• Dead code cleanup: Removed unused containerHasUIDEntryFn variable, dead execUserForAgentExec function (never called from production), and stale test mocks that referenced removed behavior.

[1.8.0] - 2026-05-08

Changed

• Runtime Engine Extraction: Extracted ~1000 lines of monolithic container orchestration from internal/agent/runner.go into a dedicated RuntimeEngine in new internal/agent/engine.go. runner.go now delegates to engine.Prepare() and engine.Execute(), centralizing daemon detection, clipboard server, SSH bridge, login forwarding, environment assembly, and container state handling.
• Security Session Interface: Introduced a new Session interface in internal/security/session_deep.go with noOpSession (disabled) and secureSession (active) implementations. Replaces direct SessionManager coupling throughout the codebase with a clean, testable abstraction.
• SecretShield Deep Module: Created internal/security/shield.go as a deep module encapsulating secret detection and redaction into a single atomic Protect() operation. integration.go now delegates scanning to SecretShield instead of orchestrating Scanner directly.
• Runner Integration Refactor: internal/security/runner_integration.go completely rewritten around the Session interface. Uses the new security.Open() factory and delegates env masking to sess.MaskEnv(). Eliminates redundant EnvMasker instantiation at every call site.
• Scanner JSON Serialization: Replaced hand-rolled string-buffer JSON generation in internal/security/scanner.go with proper encoding/json MarshalIndent/Unmarshal for manifest and redaction index I/O.
• RiPGrep Path Resolution: Changed hardcoded /usr/bin/rg stat to exec.LookPath("rg") for cross-distro compatibility.
• Session Manager Cleanup Removal: Removed Manager.Cleanup() and isProcessAlive orphan-reaping logic from internal/security/session.go. Session lifecycle is now managed explicitly through the Session interface.
• Workspace Type Override: Added CONSTRUCT_SECURITY_WORKSPACE_TYPE environment variable and WorkspaceTypeNone for testability. DetectWorkspaceType() now respects the override.
• OverlayFS Mount Fix: Corrected overlayfs mount options to use lowerdir=<lower>,upperdir=<upper>,workdir=<work> instead of the erroneous lowerdir=<lower>:<upper>,upperdir=<upper>,workdir=<work> that duplicated the upper layer in the lower stack.
• Setup PATH Construction: runSetup now constructs PATH and CONSTRUCT_PATH directly via env.BuildConstructPath() instead of the removed applyConstructPath() helper.

Added

• Clipboard Server Stop: Added Stop() method to internal/clipboard/server.go for clean listener shutdown.
• Security Session Tests: Added internal/security/session_test.go with regression coverage for both noOpSession (disabled) and secureSession (enabled with CONSTRUCT_SECURITY_WORKSPACE_TYPE=none) deep interface behavior.

Fixed

• Nil Status Guards: Added nil-pointer checks in internal/security/integration.go before calling sm.status.IsEnabled().
• CI Lint Toolchain Pin: Bumped golangci-lint pin from v2.11.4 to v2.12.2 in build and release workflows; aligned local Makefile CI pin to 2.12.2.

Removed

• ~29 Helper Functions from runner.go: Removed collectForwardedEnv, buildRunFlags, shouldEnableLoginForward, applyYoloArgs, applyConstructPath, execUserForAgentExec, appendExecUserRunFlags, resolveExecUserForRunningContainer, shouldEnableYolo, yoloFlagForAgent, readLoginBridgePorts, parsePorts, formatPorts, mapDaemonWorkdir, warnDaemonMountFallback, getEffectiveCwd, execViaDaemon, runAgentPatchInDaemon, buildDaemonExecEnv, execInRunningContainer, startDaemonSSHBridge, ensureDaemonSSHProxy, waitForDaemonSSHProxy, checkDaemonSSHProxy, startDaemonBackground, waitForDaemon, ensureAgentRuntimeDirs, appendAgentSpecificRunFlags, appendAgentSpecificDaemonEnv, and appendAgentSpecificExecEnv. All behavior preserved in RuntimeEngine.

---

[1.7.7] - 2026-05-07

Changed

• Pi Coding Agent Package: Switched from @mariozechner/pi-coding-agent to @earendil-works/pi-coding-agent in default npm packages.
• Gemini CLI Distribution: Moved gemini-cli from Homebrew to npm (@google/gemini-cli) for consistent cross-platform installation.
• OpenCode Install Source: Removed opencode from default Homebrew packages; added automatic OpenCode installation via official installer in [post_install] commands.

Removed

• **Oh My Pi Ag...

The Construct CLI 1.8.4

[1.8.4] - 2026-05-11

Added

• Global AGENTS.md Symlinks: Automatically creates symlinks to the global AGENTS.md rules file in common mount points (/workspaces/, /projects/) and their subdirectories. This ensures agents can easily discover global instructions regardless of the project's mount path or random daemon hash.

[1.8.3] - 2026-05-09

Fixed

• ARM64 Setup & agent-browser: Fixed agent-browser installation failure on ARM64 Linux by implementing an automatic wrapper that uses the system Chromium (/usr/bin/chromium).
• Resilient Package Installation: Added failure-safe command execution (cmd || echo ...) in install_user_packages.sh to prevent a single tool failure from aborting the entire setup.
• Sudo Detection: Improved SUDO_AVAILABLE check to use sudo -n apt-get --version, resolving issues in restricted sudoers environments where true was not permitted.
• Multimodal Clipboard Regression: Resolved image pasting failures in Gemini and Codex agents.
  • macOS Networking: Fixed 127.0.0.1 hardcoding in the clipboard server; now correctly uses host.docker.internal (or configured clipboard_host), making the host clipboard reachable from the container.
  • Ghostty / Bracketed Paste Support: Added PTY interception for \x1b[200~ sequences. PTY wrappers now consume bracketed paste content and inject image paths directly, bypassing terminal protocol mismatches.
  • Daemon Patching: Restored runAgentPatchInDaemon logic to ensure shims, wrappers, and Xvfb are correctly initialized in persistent daemon containers.
  • Headless X11 (Xvfb): Moved Xvfb startup to the agent-patch script to ensure a valid DISPLAY is always available for agents that expect a real display.
  • Gemini @-prefix: Ensured Gemini uses the required @path injection format while Codex uses raw paths.
• Agent Update Hardening: Added defensive command -v checks for Claude and Pi update commands in Topgrade configuration, preventing errors in environments where these agents are not installed.

Changed

• Official Goose CLI Installer: Switched to the official Goose installation script (github.com/aaif-goose/goose) for more reliable setup.
• Updated OpenCode Installer: Updated the OpenCode post-install command to use the canonical curl -fsSL https://opencode.ai/install | bash.
• Pi Update Integration: Integrated pi update into the primary Topgrade update path to ensure Pi and its internal packages are kept current during ct sys update.
• Clean Brew Installation Logs: Optimized the Homebrew installation script to check for existing packages before running brew install, replacing noisy "already installed" warnings with clean confirmation messages.

Optimized

• Fast Agent Startup (Patch Marker): Implemented a versioned marker-based guard (~/.construct_patched) to skip redundant agent clipboard patching on startup. This significantly reduces latency when entering a shell or launching an agent in a warm daemon container. Patching is now only re-triggered after Construct version changes or package installations.

[1.8.2] - 2026-05-09

Fixed

• Daemon shell with no args: execViaDaemon now defaults to the configured shell (sandbox.shell or /bin/bash) when invoked without arguments, matching the existing behavior of execInRunningContainer. Previously, ct sys shell passed an empty command to docker exec, causing "requires at least 2 arguments" error.

[1.8.1] - 2026-05-09

Fixed

• Root exec in daemon containers: resolveExecUserForRunningContainer() now returns "construct" on all code paths instead of "". Previously, docker exec -it into the daemon ran agents as root (since USER construct is commented out in the Dockerfile), causing Claude CLI to reject --dangerously-skip-permissions. Added uid==0 guard and UsesUserNamespaceRemap() check.
• Pre-existing test failure on uid=0 CI: TestAppendExecUserRunFlags now correctly handles root environments by expecting no --user flag when uid=0.
• Missing daemon launch messages: Restored "Running in Construct daemon: [args]", "Entering Construct daemon shell...", "✓ Started SSH Agent proxy (daemon)", and exit code 126/127 PATH hints that were lost in the v1.8.0 refactor.

Changed

• Claude install moved to packages.toml: Claude Code installation moved from hardcoded packages.go to [post_install] section in packages.toml, consistent with droid/opencode pattern.
• Pi self-update in update routine: Added pi update to both update-all.sh manual fallback and topgrade [commands] config.

Removed

• Dead code cleanup: Removed unused containerHasUIDEntryFn variable, dead execUserForAgentExec function (never called from production), and stale test mocks that referenced removed behavior.

[1.8.0] - 2026-05-08

Changed

• Runtime Engine Extraction: Extracted ~1000 lines of monolithic container orchestration from internal/agent/runner.go into a dedicated RuntimeEngine in new internal/agent/engine.go. runner.go now delegates to engine.Prepare() and engine.Execute(), centralizing daemon detection, clipboard server, SSH bridge, login forwarding, environment assembly, and container state handling.
• Security Session Interface: Introduced a new Session interface in internal/security/session_deep.go with noOpSession (disabled) and secureSession (active) implementations. Replaces direct SessionManager coupling throughout the codebase with a clean, testable abstraction.
• SecretShield Deep Module: Created internal/security/shield.go as a deep module encapsulating secret detection and redaction into a single atomic Protect() operation. integration.go now delegates scanning to SecretShield instead of orchestrating Scanner directly.
• Runner Integration Refactor: internal/security/runner_integration.go completely rewritten around the Session interface. Uses the new security.Open() factory and delegates env masking to sess.MaskEnv(). Eliminates redundant EnvMasker instantiation at every call site.
• Scanner JSON Serialization: Replaced hand-rolled string-buffer JSON generation in internal/security/scanner.go with proper encoding/json MarshalIndent/Unmarshal for manifest and redaction index I/O.
• RiPGrep Path Resolution: Changed hardcoded /usr/bin/rg stat to exec.LookPath("rg") for cross-distro compatibility.
• Session Manager Cleanup Removal: Removed Manager.Cleanup() and isProcessAlive orphan-reaping logic from internal/security/session.go. Session lifecycle is now managed explicitly through the Session interface.
• Workspace Type Override: Added CONSTRUCT_SECURITY_WORKSPACE_TYPE environment variable and WorkspaceTypeNone for testability. DetectWorkspaceType() now respects the override.
• OverlayFS Mount Fix: Corrected overlayfs mount options to use lowerdir=<lower>,upperdir=<upper>,workdir=<work> instead of the erroneous lowerdir=<lower>:<upper>,upperdir=<upper>,workdir=<work> that duplicated the upper layer in the lower stack.
• Setup PATH Construction: runSetup now constructs PATH and CONSTRUCT_PATH directly via env.BuildConstructPath() instead of the removed applyConstructPath() helper.

Added

• Clipboard Server Stop: Added Stop() method to internal/clipboard/server.go for clean listener shutdown.
• Security Session Tests: Added internal/security/session_test.go with regression coverage for both noOpSession (disabled) and secureSession (enabled with CONSTRUCT_SECURITY_WORKSPACE_TYPE=none) deep interface behavior.

Fixed

• Nil Status Guards: Added nil-pointer checks in internal/security/integration.go before calling sm.status.IsEnabled().
• CI Lint Toolchain Pin: Bumped golangci-lint pin from v2.11.4 to v2.12.2 in build and release workflows; aligned local Makefile CI pin to 2.12.2.

Removed

• ~29 Helper Functions from runner.go: Removed collectForwardedEnv, buildRunFlags, shouldEnableLoginForward, applyYoloArgs, applyConstructPath, execUserForAgentExec, appendExecUserRunFlags, resolveExecUserForRunningContainer, shouldEnableYolo, yoloFlagForAgent, readLoginBridgePorts, parsePorts, formatPorts, mapDaemonWorkdir, warnDaemonMountFallback, getEffectiveCwd, execViaDaemon, runAgentPatchInDaemon, buildDaemonExecEnv, execInRunningContainer, startDaemonSSHBridge, ensureDaemonSSHProxy, waitForDaemonSSHProxy, checkDaemonSSHProxy, startDaemonBackground, waitForDaemon, ensureAgentRuntimeDirs, appendAgentSpecificRunFlags, appendAgentSpecificDaemonEnv, and appendAgentSpecificExecEnv. All behavior preserved in RuntimeEngine.

---

[1.7.7] - 2026-05-07

Changed

• Pi Coding Agent Package: Switched from @mariozechner/pi-coding-agent to @earendil-works/pi-coding-agent in default npm packages.
• Gemini CLI Distribution: Moved gemini-cli from Homebrew to npm (@google/gemini-cli) for consistent cross-platform installation.
• OpenCode Install Source: Removed opencode from default Homebrew packages; added automatic OpenCode installation via official installer in [post_install] commands.

Removed

• Oh My Pi Agent: Removed omp (Oh My Pi) from supported agents. Unregistered from agent.go, help.go, memories.go, update-all.sh, packages.toml, README.md, and AGENTS.md.

---

[1.7.6] - 2026-05-03

Fixed

• OrbStack Repeated Launch: On macOS, Construct no longer brings OrbStack to the foreground on every invocation when Docker is already running in the background. startRuntime now checks docker info before ...

The Construct CLI 1.8.3

[1.8.3] - 2026-05-09

Fixed

• ARM64 Setup & agent-browser: Fixed agent-browser installation failure on ARM64 Linux by implementing an automatic wrapper that uses the system Chromium (/usr/bin/chromium).
• Resilient Package Installation: Added failure-safe command execution (cmd || echo ...) in install_user_packages.sh to prevent a single tool failure from aborting the entire setup.
• Sudo Detection: Improved SUDO_AVAILABLE check to use sudo -n apt-get --version, resolving issues in restricted sudoers environments where true was not permitted.
• Multimodal Clipboard Regression: Resolved image pasting failures in Gemini and Codex agents.
  • macOS Networking: Fixed 127.0.0.1 hardcoding in the clipboard server; now correctly uses host.docker.internal (or configured clipboard_host), making the host clipboard reachable from the container.
  • Ghostty / Bracketed Paste Support: Added PTY interception for \x1b[200~ sequences. PTY wrappers now consume bracketed paste content and inject image paths directly, bypassing terminal protocol mismatches.
  • Daemon Patching: Restored runAgentPatchInDaemon logic to ensure shims, wrappers, and Xvfb are correctly initialized in persistent daemon containers.
  • Headless X11 (Xvfb): Moved Xvfb startup to the agent-patch script to ensure a valid DISPLAY is always available for agents that expect a real display.
  • Gemini @-prefix: Ensured Gemini uses the required @path injection format while Codex uses raw paths.
• Agent Update Hardening: Added defensive command -v checks for Claude and Pi update commands in Topgrade configuration, preventing errors in environments where these agents are not installed.

Changed

• Official Goose CLI Installer: Switched to the official Goose installation script (github.com/aaif-goose/goose) for more reliable setup.
• Updated OpenCode Installer: Updated the OpenCode post-install command to use the canonical curl -fsSL https://opencode.ai/install | bash.
• Pi Update Integration: Integrated pi update into the primary Topgrade update path to ensure Pi and its internal packages are kept current during ct sys update.
• Clean Brew Installation Logs: Optimized the Homebrew installation script to check for existing packages before running brew install, replacing noisy "already installed" warnings with clean confirmation messages.

Optimized

• Fast Agent Startup (Patch Marker): Implemented a versioned marker-based guard (~/.construct_patched) to skip redundant agent clipboard patching on startup. This significantly reduces latency when entering a shell or launching an agent in a warm daemon container. Patching is now only re-triggered after Construct version changes or package installations.

[1.8.2] - 2026-05-09

Fixed

• Daemon shell with no args: execViaDaemon now defaults to the configured shell (sandbox.shell or /bin/bash) when invoked without arguments, matching the existing behavior of execInRunningContainer. Previously, ct sys shell passed an empty command to docker exec, causing "requires at least 2 arguments" error.

[1.8.1] - 2026-05-09

Fixed

• Root exec in daemon containers: resolveExecUserForRunningContainer() now returns "construct" on all code paths instead of "". Previously, docker exec -it into the daemon ran agents as root (since USER construct is commented out in the Dockerfile), causing Claude CLI to reject --dangerously-skip-permissions. Added uid==0 guard and UsesUserNamespaceRemap() check.
• Pre-existing test failure on uid=0 CI: TestAppendExecUserRunFlags now correctly handles root environments by expecting no --user flag when uid=0.
• Missing daemon launch messages: Restored "Running in Construct daemon: [args]", "Entering Construct daemon shell...", "✓ Started SSH Agent proxy (daemon)", and exit code 126/127 PATH hints that were lost in the v1.8.0 refactor.

Changed

• Claude install moved to packages.toml: Claude Code installation moved from hardcoded packages.go to [post_install] section in packages.toml, consistent with droid/opencode pattern.
• Pi self-update in update routine: Added pi update to both update-all.sh manual fallback and topgrade [commands] config.

Removed

• Dead code cleanup: Removed unused containerHasUIDEntryFn variable, dead execUserForAgentExec function (never called from production), and stale test mocks that referenced removed behavior.

[1.8.0] - 2026-05-08

Changed

• Runtime Engine Extraction: Extracted ~1000 lines of monolithic container orchestration from internal/agent/runner.go into a dedicated RuntimeEngine in new internal/agent/engine.go. runner.go now delegates to engine.Prepare() and engine.Execute(), centralizing daemon detection, clipboard server, SSH bridge, login forwarding, environment assembly, and container state handling.
• Security Session Interface: Introduced a new Session interface in internal/security/session_deep.go with noOpSession (disabled) and secureSession (active) implementations. Replaces direct SessionManager coupling throughout the codebase with a clean, testable abstraction.
• SecretShield Deep Module: Created internal/security/shield.go as a deep module encapsulating secret detection and redaction into a single atomic Protect() operation. integration.go now delegates scanning to SecretShield instead of orchestrating Scanner directly.
• Runner Integration Refactor: internal/security/runner_integration.go completely rewritten around the Session interface. Uses the new security.Open() factory and delegates env masking to sess.MaskEnv(). Eliminates redundant EnvMasker instantiation at every call site.
• Scanner JSON Serialization: Replaced hand-rolled string-buffer JSON generation in internal/security/scanner.go with proper encoding/json MarshalIndent/Unmarshal for manifest and redaction index I/O.
• RiPGrep Path Resolution: Changed hardcoded /usr/bin/rg stat to exec.LookPath("rg") for cross-distro compatibility.
• Session Manager Cleanup Removal: Removed Manager.Cleanup() and isProcessAlive orphan-reaping logic from internal/security/session.go. Session lifecycle is now managed explicitly through the Session interface.
• Workspace Type Override: Added CONSTRUCT_SECURITY_WORKSPACE_TYPE environment variable and WorkspaceTypeNone for testability. DetectWorkspaceType() now respects the override.
• OverlayFS Mount Fix: Corrected overlayfs mount options to use lowerdir=<lower>,upperdir=<upper>,workdir=<work> instead of the erroneous lowerdir=<lower>:<upper>,upperdir=<upper>,workdir=<work> that duplicated the upper layer in the lower stack.
• Setup PATH Construction: runSetup now constructs PATH and CONSTRUCT_PATH directly via env.BuildConstructPath() instead of the removed applyConstructPath() helper.

Added

• Clipboard Server Stop: Added Stop() method to internal/clipboard/server.go for clean listener shutdown.
• Security Session Tests: Added internal/security/session_test.go with regression coverage for both noOpSession (disabled) and secureSession (enabled with CONSTRUCT_SECURITY_WORKSPACE_TYPE=none) deep interface behavior.

Fixed

• Nil Status Guards: Added nil-pointer checks in internal/security/integration.go before calling sm.status.IsEnabled().
• CI Lint Toolchain Pin: Bumped golangci-lint pin from v2.11.4 to v2.12.2 in build and release workflows; aligned local Makefile CI pin to 2.12.2.

Removed

• ~29 Helper Functions from runner.go: Removed collectForwardedEnv, buildRunFlags, shouldEnableLoginForward, applyYoloArgs, applyConstructPath, execUserForAgentExec, appendExecUserRunFlags, resolveExecUserForRunningContainer, shouldEnableYolo, yoloFlagForAgent, readLoginBridgePorts, parsePorts, formatPorts, mapDaemonWorkdir, warnDaemonMountFallback, getEffectiveCwd, execViaDaemon, runAgentPatchInDaemon, buildDaemonExecEnv, execInRunningContainer, startDaemonSSHBridge, ensureDaemonSSHProxy, waitForDaemonSSHProxy, checkDaemonSSHProxy, startDaemonBackground, waitForDaemon, ensureAgentRuntimeDirs, appendAgentSpecificRunFlags, appendAgentSpecificDaemonEnv, and appendAgentSpecificExecEnv. All behavior preserved in RuntimeEngine.

---

[1.7.7] - 2026-05-07

Changed

• Pi Coding Agent Package: Switched from @mariozechner/pi-coding-agent to @earendil-works/pi-coding-agent in default npm packages.
• Gemini CLI Distribution: Moved gemini-cli from Homebrew to npm (@google/gemini-cli) for consistent cross-platform installation.
• OpenCode Install Source: Removed opencode from default Homebrew packages; added automatic OpenCode installation via official installer in [post_install] commands.

Removed

• Oh My Pi Agent: Removed omp (Oh My Pi) from supported agents. Unregistered from agent.go, help.go, memories.go, update-all.sh, packages.toml, README.md, and AGENTS.md.

---

[1.7.6] - 2026-05-03

Fixed

• OrbStack Repeated Launch: On macOS, Construct no longer brings OrbStack to the foreground on every invocation when Docker is already running in the background. startRuntime now checks docker info before launching OrbStack, avoiding redundant open -a OrbStack calls.

---

[1.7.5] - 2026-05-02

Fixed

• pnpm Update False Failure: ct sys update reported pnpm: FAILED because topgrade's native pnpm step exits non-zero when pnpm is managed by Homebrew. Topgrade's pnpm step is now disabled — brew alre...

The Construct CLI 1.8.2

[1.8.2] - 2026-05-09

Fixed

• Daemon shell with no args: execViaDaemon now defaults to the configured shell (sandbox.shell or /bin/bash) when invoked without arguments, matching the existing behavior of execInRunningContainer. Previously, ct sys shell passed an empty command to docker exec, causing "requires at least 2 arguments" error.

[1.8.1] - 2026-05-09

Fixed

• Root exec in daemon containers: resolveExecUserForRunningContainer() now returns "construct" on all code paths instead of "". Previously, docker exec -it into the daemon ran agents as root (since USER construct is commented out in the Dockerfile), causing Claude CLI to reject --dangerously-skip-permissions. Added uid==0 guard and UsesUserNamespaceRemap() check.
• Pre-existing test failure on uid=0 CI: TestAppendExecUserRunFlags now correctly handles root environments by expecting no --user flag when uid=0.
• Missing daemon launch messages: Restored "Running in Construct daemon: [args]", "Entering Construct daemon shell...", "✓ Started SSH Agent proxy (daemon)", and exit code 126/127 PATH hints that were lost in the v1.8.0 refactor.

Changed

• Claude install moved to packages.toml: Claude Code installation moved from hardcoded packages.go to [post_install] section in packages.toml, consistent with droid/opencode pattern.
• Pi self-update in update routine: Added pi update to both update-all.sh manual fallback and topgrade [commands] config.

Removed

• Dead code cleanup: Removed unused containerHasUIDEntryFn variable, dead execUserForAgentExec function (never called from production), and stale test mocks that referenced removed behavior.

[1.8.0] - 2026-05-08

Changed

• Runtime Engine Extraction: Extracted ~1000 lines of monolithic container orchestration from internal/agent/runner.go into a dedicated RuntimeEngine in new internal/agent/engine.go. runner.go now delegates to engine.Prepare() and engine.Execute(), centralizing daemon detection, clipboard server, SSH bridge, login forwarding, environment assembly, and container state handling.
• Security Session Interface: Introduced a new Session interface in internal/security/session_deep.go with noOpSession (disabled) and secureSession (active) implementations. Replaces direct SessionManager coupling throughout the codebase with a clean, testable abstraction.
• SecretShield Deep Module: Created internal/security/shield.go as a deep module encapsulating secret detection and redaction into a single atomic Protect() operation. integration.go now delegates scanning to SecretShield instead of orchestrating Scanner directly.
• Runner Integration Refactor: internal/security/runner_integration.go completely rewritten around the Session interface. Uses the new security.Open() factory and delegates env masking to sess.MaskEnv(). Eliminates redundant EnvMasker instantiation at every call site.
• Scanner JSON Serialization: Replaced hand-rolled string-buffer JSON generation in internal/security/scanner.go with proper encoding/json MarshalIndent/Unmarshal for manifest and redaction index I/O.
• RiPGrep Path Resolution: Changed hardcoded /usr/bin/rg stat to exec.LookPath("rg") for cross-distro compatibility.
• Session Manager Cleanup Removal: Removed Manager.Cleanup() and isProcessAlive orphan-reaping logic from internal/security/session.go. Session lifecycle is now managed explicitly through the Session interface.
• Workspace Type Override: Added CONSTRUCT_SECURITY_WORKSPACE_TYPE environment variable and WorkspaceTypeNone for testability. DetectWorkspaceType() now respects the override.
• OverlayFS Mount Fix: Corrected overlayfs mount options to use lowerdir=<lower>,upperdir=<upper>,workdir=<work> instead of the erroneous lowerdir=<lower>:<upper>,upperdir=<upper>,workdir=<work> that duplicated the upper layer in the lower stack.
• Setup PATH Construction: runSetup now constructs PATH and CONSTRUCT_PATH directly via env.BuildConstructPath() instead of the removed applyConstructPath() helper.

Added

• Clipboard Server Stop: Added Stop() method to internal/clipboard/server.go for clean listener shutdown.
• Security Session Tests: Added internal/security/session_test.go with regression coverage for both noOpSession (disabled) and secureSession (enabled with CONSTRUCT_SECURITY_WORKSPACE_TYPE=none) deep interface behavior.

Fixed

• Nil Status Guards: Added nil-pointer checks in internal/security/integration.go before calling sm.status.IsEnabled().
• CI Lint Toolchain Pin: Bumped golangci-lint pin from v2.11.4 to v2.12.2 in build and release workflows; aligned local Makefile CI pin to 2.12.2.

Removed

• ~29 Helper Functions from runner.go: Removed collectForwardedEnv, buildRunFlags, shouldEnableLoginForward, applyYoloArgs, applyConstructPath, execUserForAgentExec, appendExecUserRunFlags, resolveExecUserForRunningContainer, shouldEnableYolo, yoloFlagForAgent, readLoginBridgePorts, parsePorts, formatPorts, mapDaemonWorkdir, warnDaemonMountFallback, getEffectiveCwd, execViaDaemon, runAgentPatchInDaemon, buildDaemonExecEnv, execInRunningContainer, startDaemonSSHBridge, ensureDaemonSSHProxy, waitForDaemonSSHProxy, checkDaemonSSHProxy, startDaemonBackground, waitForDaemon, ensureAgentRuntimeDirs, appendAgentSpecificRunFlags, appendAgentSpecificDaemonEnv, and appendAgentSpecificExecEnv. All behavior preserved in RuntimeEngine.

---

[1.7.7] - 2026-05-07

Changed

• Pi Coding Agent Package: Switched from @mariozechner/pi-coding-agent to @earendil-works/pi-coding-agent in default npm packages.
• Gemini CLI Distribution: Moved gemini-cli from Homebrew to npm (@google/gemini-cli) for consistent cross-platform installation.
• OpenCode Install Source: Removed opencode from default Homebrew packages; added automatic OpenCode installation via official installer in [post_install] commands.

Removed

• Oh My Pi Agent: Removed omp (Oh My Pi) from supported agents. Unregistered from agent.go, help.go, memories.go, update-all.sh, packages.toml, README.md, and AGENTS.md.

---

[1.7.6] - 2026-05-03

Fixed

• OrbStack Repeated Launch: On macOS, Construct no longer brings OrbStack to the foreground on every invocation when Docker is already running in the background. startRuntime now checks docker info before launching OrbStack, avoiding redundant open -a OrbStack calls.

---

[1.7.5] - 2026-05-02

Fixed

• pnpm Update False Failure: ct sys update reported pnpm: FAILED because topgrade's native pnpm step exits non-zero when pnpm is managed by Homebrew. Topgrade's pnpm step is now disabled — brew already handles pnpm updates.

---

[1.7.4] - 2026-04-28

Fixed

• OpenCode First-Run SQLite Error: Pre-creates ~/.local/share/opencode and ~/.config/opencode directories before container startup, preventing the DrizzleError: Failed to run the query 'PRAGMA journal_mode = WAL' failure that occurred on first run in a fresh Construct environment.

---

[1.7.3] - 2026-04-27

Changed

• Expanded Default Env Passthroughs: Fresh configs now default sandbox.env_passthrough to include GITHUB_TOKEN, GEMINI_API_KEY, OPENAI_API_KEY, ANTHROPIC_API_KEY, QWEN_API_KEY, MINIMAX_API_KEY, KIMI_API_KEY, ZAI_API_KEY, MIMO_API_KEY, OPENCODE_API_KEY, and CONTEXT7_API_KEY.

---

[1.7.2] - 2026-04-21

Added

• Host Service Env: New host_service_env field in [sandbox] config section. Injects environment variables into the container with localhost/127.0.0.1 automatically rewritten to host.docker.internal. Enables agents inside the sandbox to reach host services like AgentMemory without complex IP detection. Example: "AGENTMEMORY_URL=http://localhost:3111".
• AgentMemory config directory (~/.agentmemory) is now created on container first run.

Changed

• Replaced the [bridge] configuration section and internal/bridge package (IP detection, gateway probing, CONSTRUCT_* env vars) with the simpler host_service_env mechanism. The old [bridge] config is no longer recognized and should be removed from config.toml.

Removed

• Deleted internal/bridge/ package (config, detector, injector, integration).
• Removed [bridge] section from config template and BridgeConfig type.

---

[1.7.1] - 2026-04-20

Added

• Daemon Restart Command: New construct sys daemon restart command that stops and starts the daemon container in one operation. Handles all container states: missing (starts), stopped (cleans up and starts), and running (stops then starts).

---

[1.7.0] - 2026-04-16

Changed

• Host Service Env: Replaced the [bridge] configuration section with host_service_env in [sandbox]. Configure environment variables that are injected into the container with localhost/127.0.0.1 automatically rewritten to host.docker.internal, enabling agents to reach host services (e.g., AgentMemory) without complex IP detection.

---

[1.6.4] - 2026-04-11

Added

• Hide Secrets Allowlist: Added hide_secrets_allow_paths configuration option to exclude specific files from redaction. This allo...