[FEATURE] Side channel for CLI tools to emit context information

Preflight Checklist

• [x] I have searched existing requests and this feature hasn't been requested yet
• [x] This is a single feature request (not multiple features)

Problem Statement

AIs often invoke CLI tooling incorrectly, since there is no standard CLI schema like there is for MCP. CLI tooling that wants to better support AI could detect that they are being invoked by an AI harness (e.g. by checking for a characteristic environment variable like $CLAUDECODE) and emit hints (which could be as straightforward as --help output) to the model over stderr. The problem is that models typically generate invocations like:

some-cmd 2>&1 | grep SomeSpecificThing | tail -5

This greatly reduces the odds that the AI will perceive the tool's feedback at its first opportunity. The best-case scenario is that the tool follows up with some-cmd --help, which adds a round trip; it's just as likely, however, that the model will do something more dysfunctional, like continue guessing at invocations, or try to brute force the problem through some other means that isn't as well-suited to solving the problem.

Proposed Solution

Kiro CLI offers a special side channel to CLI tooling: instead of stdout or stderr, tools can write to $AGENT_CONTEXT_OUT, which is implemented as a FIFO that the harness listens on. Output written to this channel is guaranteed to reach the harness unfiltered; this is analogous to the intended behavior of stderr in interactive, human uses of the shell.

Alternative Solutions

1. A more systematic convention, standard, or schema for preexisting CLI tooling would reduce or eliminate the need for this feature.
2. The models could be trained or steered to stop redirecting stderr to stdout, and to stop defensively filtering/truncating standard output (which should be left to the harness). There is a decades-old convention of "stdout is for programs, stderr is for humans," and the current observed behavior of AIs is not in line with this convention.

Priority

Medium - would be very helpful

Feature Category

CLI commands and flags

Use Case Example

As an owner of CLI tooling, I can use this environment variable to implement use cases like:

1. Write AI-tuned --help output to context in response to invalid invocations
2. Write verbose output to a separate log file and then tell the AI where it is, in order to prevent repeat invocations to slice-and-dice the output in different ways
3. Suggest that complementary skills or MCP tools be loaded and used, rather than calling the CLI directly

Additional Context

_No response_