@gkoreli/ghx 2.4.2 → 2.6.0

package/README.md

@@ -68,8 +68,18 @@ you can `ls` and `jq`:
     logs.jsonl                # GenAI-convention message-content records
     metrics.jsonl             # duration, token, report-size metrics
     tier-decisions.jsonl      # escalation policy evaluation per turn (which tier, why)
+    live.jsonl                # realtime turn activity, appended as it happens
 ```
 
+The OTLP artifacts are written when a question completes; `live.jsonl` streams
+turn activity in realtime — turn start/end, text and thought chunks, every tool
+call and update as the agent works — so
+`tail -f ~/.ghx/sessions/<name>/live.jsonl` watches a running question instead
+of waiting minutes for the final report
+(see [ADR-0022.1](docs/adr/0022.1-live-turn-log.md)). `ghx sidecar tail --follow`
+renders that stream as one human-readable line per event, so you rarely need
+the raw `tail -f`.
+
 Sessions persist, so follow-up questions on the same repo are cheaper and
 context-aware. The traces are **official OpenTelemetry** (OTLP/JSON, GenAI
 semantic conventions) — any industry tool consumes them in seconds, and
@@ -167,6 +177,57 @@ ghx sidecar config init --claude-acp    # writes ~/.ghx/config.json with the ACP
 Re-running `config init --claude-acp` against an existing config shows a field
 diff and refuses to overwrite without `--force`.
 
+**Using your installed Claude Code (toolbox / wrapper builds).** The adapter's
+SDK ships its own bundled Claude Code binary and its own credential store — by
+default your `claude` on PATH (and its `~/.claude/settings.json`, credential
+hooks, model aliases) is **not** what runs. If your organization installs a
+wrapped `claude` that carries work credentials, point the adapter at it with
+`CLAUDE_CODE_EXECUTABLE` (honored by `claude-agent-acp` ≥ 0.55):
+
+```json
+{
+  "agent": "env CLAUDE_CODE_EXECUTABLE=/path/to/your/claude npx -y @agentclientprotocol/claude-agent-acp@0.55.0"
+}
+```
+
+`ghx sidecar config init --claude-exe /path/to/your/claude` writes exactly this
+config for you (`--claude-exe auto` resolves `claude` from your PATH; the same
+diff-and-`--force` rules apply).
+
+> **Known upstream issue (enterprise wrapper builds):** when
+> `CLAUDE_CODE_EXECUTABLE` points at a *wrapper* script/binary (e.g. a
+> corporate toolbox `claude` that resolves credentials itself), the adapter
+> can hang indefinitely at prompt time: ghx legitimately sends ACP
+> `settingSources: []` for session isolation, and some wrappers stall instead
+> of erroring when settings loading is suppressed (isolated 2026-07-06:
+> `settingSources: []` alone reproduces the hang; `strictMcpConfig` and
+> `tools` do not; mechanism: the native binary resolves Bedrock
+> `modelOverrides` from `~/.claude/settings.json` and stalls instead of
+> erroring when that read is suppressed). The fix is one config line:
+>
+> ```json
+> {
+>   "agent": "env CLAUDE_CODE_EXECUTABLE=/path/to/your/claude npx -y @agentclientprotocol/claude-agent-acp@0.55.0",
+>   "agentSettingSources": ["user"]
+> }
+> ```
+>
+> `agentSettingSources` opts the spawned agent into loading your user
+> settings (`~/.claude/settings.json`) so the wrapper's model aliases and
+> credential hooks work. It deliberately weakens session isolation — host
+> user settings apply to sidecar sessions — which is why it is opt-in and
+> off by default (ADR-0033.2). Wrapping the *adapter* in a script that
+> exports auth env itself remains a valid alternative.
+
+Embedding `env VAR=...` in the agent command makes the setting travel with the
+command itself, so it works no matter which process (CLI or resident daemon)
+spawns the agent. Exporting `CLAUDE_CODE_EXECUTABLE` in your shell also works:
+every ask forwards auth-relevant env to the agent
+([ADR-0033.1](docs/adr/0033.1-client-auth-env-passthrough.md)), and the same
+applies to Bedrock/Vertex/gateway env (`CLAUDE_CODE_USE_BEDROCK`, `AWS_*`,
+`ANTHROPIC_BASE_URL`, ...). `ghx sidecar doctor` shows exactly which names your
+shell would forward.
+
 ### 3. Verify
 
 ```bash
@@ -222,6 +283,7 @@ ghx sidecar sessions list                 # all sessions
 ghx sidecar sessions show <session>       # details + report history
 ghx sidecar sessions ledger <session>     # the accumulated evidence ledger
 ghx sidecar sessions reroute <s> <turn> <dest>  # move a mis-routed turn; both ledgers rebuilt by replay
+ghx sidecar tail [session] --follow       # human-readable live view of a running question
 ghx sidecar view [session]                # spawn a local trace UI over the session's artifacts
 ghx sidecar view --list                   # sessions with turn/report counts
 ghx sidecar view --port 9000              # viewer UI port (default 8000)
@@ -366,6 +428,7 @@ ghx sidecar sessions list                   # List persisted sidecar sessions
 ghx sidecar sessions show <session>         # Metadata + report history
 ghx sidecar sessions ledger <session>       # Accumulated evidence ledger JSON
 ghx sidecar sessions reroute <s> <turn> <dest> # Move a mis-routed turn and rebuild ledgers
+ghx sidecar tail [session] --follow         # Human-readable live view of turn activity (live.jsonl)
 ghx sidecar view [session]                  # Local OTel viewer over session artifacts
 ghx sidecar evals export --format sft --run <dir> --out <file> # Export committed eval episodes
 ghx sidecar report-sink --out <path>        # Internal report-sink MCP server used by ACP turns
@@ -405,9 +468,12 @@ the binary codemap needs for `--importers`/`--deps`), and `local:repomap`
 stolen with attribution from
 [aider's repo map](https://github.com/Aider-AI/aider), Apache-2.0 — an
 algorithm, not a dependency; deterministic given the same snapshot and
-query). If a tool binary is missing, ghx prints the install hint and exits
-before any clone; answers fall back to remote Tier-1 evidence — never a
-silent or faked Tier-2 result. `astgrep` follows grep parity: exit `1` with
+query). Only `local:repomap` works with zero extra installs; codemap and
+ast-grep are optional external binaries, and `ghx sidecar doctor` reports
+which tier-2 backends resolve on your machine with install hints for the
+missing ones. If a tool binary is missing, ghx prints the install hint and
+exits before any clone; answers fall back to remote Tier-1 evidence — never
+a silent or faked Tier-2 result. `astgrep` follows grep parity: exit `1` with
 `[]` means the search ran and found nothing.
 
 When the sidecar answers a question, escalation is never vibes: every turn

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gkoreli/ghx",
-  "version": "2.4.2",
+  "version": "2.6.0",
   "description": "Agent-first GitHub code exploration. GraphQL batching, code maps, codemode TypeScript sandbox, MCP server.",
   "bin": {
     "ghx": "npm/bin/ghx"
@@ -28,11 +28,11 @@
     "node": ">=16"
   },
   "optionalDependencies": {
-    "@gkoreli/ghx-darwin-arm64": "2.4.2",
-    "@gkoreli/ghx-darwin-x64": "2.4.2",
-    "@gkoreli/ghx-linux-arm64": "2.4.2",
-    "@gkoreli/ghx-linux-x64": "2.4.2",
-    "@gkoreli/ghx-win32-arm64": "2.4.2",
-    "@gkoreli/ghx-win32-x64": "2.4.2"
+    "@gkoreli/ghx-darwin-arm64": "2.6.0",
+    "@gkoreli/ghx-darwin-x64": "2.6.0",
+    "@gkoreli/ghx-linux-arm64": "2.6.0",
+    "@gkoreli/ghx-linux-x64": "2.6.0",
+    "@gkoreli/ghx-win32-arm64": "2.6.0",
+    "@gkoreli/ghx-win32-x64": "2.6.0"
   }
 }