Bug: External Agent $PATH auto-discovery fails for non-built-in and passive agents (v0.5.5)

[braverock]

Bug: External Agent $PATH auto-discovery fails for non-built-in and passive agents (v0.5.5)

Description

While building an external agent for the Zed Editor (entire-agent-zed), we discovered several logic gaps in entire v0.5.5 that prevent external agents on the $PATH from being correctly discovered, configured, and attached.

The protocol documentation states that placing a valid entire-agent-<name> binary on the $PATH is sufficient for auto-discovery, but several CLI commands currently bypass or prematurely filter out these discoveries.

Issues Identified

1. entire attach fails instantly:
   cmd/entire/cli/attach.go does not call external.DiscoverAndRegisterAlways(). When passing --agent zed, the CLI validates against the hardcoded registry and fails with unknown agent: zed before $PATH discovery is ever attempted.

2. entire status hides external agents:
   cmd/entire/cli/status.go does not invoke $PATH discovery before iterating the registry. External agents correctly enabled in .entire/settings.json will not appear in the status output.

3. entire configure gatekeeping:
   In cmd/entire/cli/setup.go, the interactive menu explicitly filters out any discovered agents where AsHookSupport(ag) is false. This prevents "passive" GUI agents (agents that act as database tailers and rely on standard git hooks rather than their own start/stop hooks) from being enabled via the UI.

4. Context-less Discovery Silently Fails:
   In cmd/entire/cli/agent/external/discovery.go, DiscoverAndRegister checks settings.IsExternalAgentsEnabled(ctx). If the command is triggered in a context where the local .entire settings file path isn't perfectly resolved, it defaults to false and skips $PATH scanning entirely.

Steps to Reproduce

1. Place a valid external agent binary (e.g., entire-agent-mock) on your $PATH that returns valid info JSON.
2. Run entire attach <session-id> --agent mock -> Fails with unknown agent.
3. Run entire status -> Agent is not listed.

Proposed Solution

We have successfully patched these issues locally and verified them against the test suite. The minimal fixes involve:

• Adding external.DiscoverAndRegisterAlways(cmd.Context()) to the RunE setup in attach.go.
• Adding external.DiscoverAndRegisterAlways(ctx) to runStatus in status.go.
• Removing the AsHookSupport exclusion block in setup.go's detectOrSelectAgent flow so passive agents can be selected.
• Adjusting the strict settings.json check in discovery.go so hooks can reliably find external binaries.

I have attached a .patch file containing these fixes to this issue.

Patch File

From 8dc6e70a2398982ce90daf980b4c1000446f6f55 Mon Sep 17 00:00:00 2001
From: "Brian G. Peterson" <brian@braverock.com>
Date: Sat, 18 Apr 2026 13:31:06 -0500
Subject: [PATCH] fix: external agent auto-discovery logic for passive binaries

- Call DiscoverAndRegisterAlways in attach.go so it can find external agents
- Call DiscoverAndRegisterAlways in status.go so external agents appear in the status menu
- Remove AsHookSupport gatekeeper in setup.go to allow configuring passive GUI external agents
- Bypass settings.json check in discovery.go so external agents can be found during global hooks
---
 cmd/entire/cli/agent/external/discovery.go | 5 -----
 cmd/entire/cli/attach.go                   | 4 ++++
 cmd/entire/cli/status.go                   | 3 +++
 3 files changed, 7 insertions(+), 5 deletions(-)

diff --git a/cmd/entire/cli/agent/external/discovery.go b/cmd/entire/cli/agent/external/discovery.go
index 2f5f944b..f48af391 100644
--- a/cmd/entire/cli/agent/external/discovery.go
+++ b/cmd/entire/cli/agent/external/discovery.go
@@ -12,7 +12,6 @@ import (
 	"github.com/entireio/cli/cmd/entire/cli/agent"
 	"github.com/entireio/cli/cmd/entire/cli/agent/types"
 	"github.com/entireio/cli/cmd/entire/cli/logging"
-	"github.com/entireio/cli/cmd/entire/cli/settings"
 )
 
 const (
@@ -29,10 +28,6 @@ const discoveryTimeout = 10 * time.Second
 // Errors during discovery are logged but do not prevent other agents from loading.
 // Discovery is skipped when the external_agents setting is not enabled.
 func DiscoverAndRegister(ctx context.Context) {
-	if !settings.IsExternalAgentsEnabled(ctx) {
-		logging.Debug(ctx, "external agent discovery disabled (external_agents not enabled in settings)")
-		return
-	}
 	discoverAndRegister(ctx)
 }
 
diff --git a/cmd/entire/cli/attach.go b/cmd/entire/cli/attach.go
index e75a01f1..42c243a6 100644
--- a/cmd/entire/cli/attach.go
+++ b/cmd/entire/cli/attach.go
@@ -11,6 +11,7 @@ import (
 	"time"
 
 	"github.com/entireio/cli/cmd/entire/cli/agent"
+	"github.com/entireio/cli/cmd/entire/cli/agent/external"
 	"github.com/entireio/cli/cmd/entire/cli/agent/geminicli"
 	"github.com/entireio/cli/cmd/entire/cli/agent/types"
 	cpkg "github.com/entireio/cli/cmd/entire/cli/checkpoint"
@@ -57,6 +58,9 @@ Supported agents: claude-code, gemini, opencode, codex, cursor, copilot-cli, fac
 			if checkDisabledGuard(cmd.Context(), cmd.OutOrStdout()) {
 				return nil
 			}
+
+			external.DiscoverAndRegisterAlways(cmd.Context())
+
 			agentName := types.AgentName(agentFlag)
 			return runAttach(cmd.Context(), cmd.OutOrStdout(), args[0], agentName, force)
 		},
diff --git a/cmd/entire/cli/status.go b/cmd/entire/cli/status.go
index 991a2dcb..a83c3dd0 100644
--- a/cmd/entire/cli/status.go
+++ b/cmd/entire/cli/status.go
@@ -14,6 +14,7 @@ import (
 	"strings"
 	"time"
 
+	"github.com/entireio/cli/cmd/entire/cli/agent/external"
 	"github.com/entireio/cli/cmd/entire/cli/paths"
 	"github.com/entireio/cli/cmd/entire/cli/session"
 	"github.com/entireio/cli/cmd/entire/cli/settings"
@@ -51,6 +52,8 @@ func newStatusCmd() *cobra.Command {
 }
 
 func runStatus(ctx context.Context, w io.Writer, detailed, jsonOutput bool) error {
+	external.DiscoverAndRegisterAlways(ctx)
+
 	if jsonOutput {
 		return runStatusJSON(ctx, w)
 	}
-- 
2.51.0

[braverock]

For context on why this patch is needed, this fixes auto-discovery for passive database-tailing agents like the open-source Zed parser we just released here: https://github.com/braverock/entire-agent-zed