Skip to content

add support for compatible custom tools (compatible_with)#550

Open
johnrichardrinehart wants to merge 1 commit intoasheshgoplani:mainfrom
johnrichardrinehart:fix/compatible-with-tool-overrides
Open

add support for compatible custom tools (compatible_with)#550
johnrichardrinehart wants to merge 1 commit intoasheshgoplani:mainfrom
johnrichardrinehart:fix/compatible-with-tool-overrides

Conversation

@johnrichardrinehart
Copy link
Copy Markdown
Contributor

@johnrichardrinehart johnrichardrinehart commented Apr 9, 2026

Summary

  • add support for compatible custom tools via a new compatible_with setting
  • preserve the configured custom tool identity instead of rewriting wrapper tools to built-in names during tmux detection
  • route Codex compatibility paths through the configured wrapper command so restart, resume, parsing, hooks, and session tracking keep using the custom tool

Example configuration

[tools.my-codex]
command = "my-codex"
compatible_with = "codex"
icon = "💻"

This lets my-codex behave like Codex for agent-deck feature handling while still preserving the custom tool name and command.

Example wrapper script

#!/usr/bin/env bash
set -euo pipefail

export OPENAI_API_KEY="${OPENAI_API_KEY:?missing OPENAI_API_KEY}"
exec codex "$@"

For example, save that as ~/bin/my-codex, make it executable, and then point the tool config at my-codex.

Testing

  • go test ./...
  • manual validation with a custom wrapper configured as compatible_with = "codex"
  • confirmed that restart/resume continues to use the wrapper command rather than falling back to plain codex
  • confirmed that the custom tool identity is preserved instead of being rewritten to the built-in tool name

Notes

  • this has been tested with compatible_with = "codex" and it is working great
  • this branch is currently stacked on top of fix(test): stabilize tmux-backed test suites #551, which contains the test-suite stabilization changes used while validating this work

@johnrichardrinehart johnrichardrinehart force-pushed the fix/compatible-with-tool-overrides branch from b40cc22 to a541040 Compare April 9, 2026 02:02
@johnrichardrinehart
Copy link
Copy Markdown
Contributor Author

This branch is now rebased on top of #551. GitHub cannot set a PR base to a fork-only branch, so #550 still targets main, but reviewers should treat #551 as the prerequisite lower PR in the stack.

@johnrichardrinehart johnrichardrinehart changed the title fix(session): preserve custom tool identity for compatible wrappers add support for compatible custom tools (compatible_with) Apr 9, 2026
@johnrichardrinehart johnrichardrinehart force-pushed the fix/compatible-with-tool-overrides branch 4 times, most recently from ef2ffe9 to 8502330 Compare April 13, 2026 18:25
The attached-session path can leak terminal reply bytes back into Agent Deck's
Bubble Tea UI during rapid attach/detach cycles. In practice this showed up as
literal fragments such as `(0.44.0)/d3d3/f5f5/d3d3/f5f5(0.44.0)...` appearing
in the TUI after repeating:

- attach to a tmux-backed session
- detach with `Ctrl+Q`
- reattach and press `Enter` a few times

Relevant environment from the repro:

- Agent Deck running inside tmux
- Bubble Tea UI on the host side
- terminal-emulator replies arriving on stdin during redraw / teardown
- the visible reply fragments included terminal version and color-report text

The underlying problem is that terminal protocol replies are not user input, but
we were still letting them cross the attach/detach boundary. The fix here keeps
that handling bounded to those lifecycle edges and treats the problem from first
principles:

- add a small stateful terminal-reply filter that understands protocol classes
  instead of matching terminal-specific payload strings
- discard escape-string replies generically (OSC, DCS, APC, PM, SOS)
- discard non-keyboard CSI replies during the short quarantine window
- preserve normal keyboard input, including CSI/SS3 key sequences such as
  arrows, Home/End, Backtab, and CSI-u key events
- reuse the same filter in both the tmux attach path and the keyboard
  compatibility reader so split replies are handled consistently across reads

This intentionally avoids keying behavior to a specific terminal emulator,
terminal version, or tmux version. The parser is based on control-sequence
structure, not on reply payload contents.

Constraint: normal keyboard input must survive immediately after attach/detach,
including CSI/SS3-based keys

Rejected alternatives:

- match terminal-specific payload strings
  - too brittle against emulator or multiplexer version changes
- drop all CSI traffic during the quarantine window
  - would break legitimate keyboard input
- keep extending PTY drain timeouts alone
  - the failing bytes were arriving on stdin as protocol replies, not just on
    PTY output

Tested:

- `nix shell nixpkgs#go nixpkgs#gcc -c go test ./internal/tmux ./internal/ui ./internal/termreply -run 'TestCleanupAttach_|TestCSIuReader(DropsTerminalRepliesDuringQuarantine|DropsSplitTerminalRepliesDuringQuarantine|PreservesNormalInputDuringQuarantine)|TestFilter'`

Not tested:

- a fresh packaged build exercised manually through repeated `Ctrl+Q` / `Enter`
  cycles after this exact commit
@johnrichardrinehart johnrichardrinehart force-pushed the fix/compatible-with-tool-overrides branch from 8502330 to 6f31dba Compare April 13, 2026 18:35
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant