The command line has a protocol server mode for third-party clients. It works over standard streams and exchanges messages one per line: initialization, authentication, creating or loading a session, sending a prompt, a stream of updates, a permission request and, if needed, cancellation. This is the case where the order of messages is part of the contract rather than an implementation detail: a missing initialization or a prompt sent before a session exists does not degrade anything, it fails outright, and the failure has to be untangled at the protocol level rather than in the application log.
The most frequent mistake when writing such a client is ignoring the permission request. The client must answer with one of the options: allow once, allow always or reject. If there is no answer, tool execution simply hangs, and from the outside it looks like a stuck agent. The mistake is all the more insidious because on simple scenarios without tools the client works fine: the first prompts are answered with text and ask for nothing, and the problem surfaces later, when the agent first decides to read a file or run a command.
More down-to-earth things live nearby: setting up terminal integration, the shell mode and configuration for a cloud model provider. What unites them is that they are all about the environment rather than the agent. And it is the environment that most often turns out to be the cause of unclear failures - especially in a corporate network, where someone else's infrastructure sits between the process and the service, infrastructure whose existence the developer usually learns about from an error message.
Proxies and certificates deserve separate treatment, because this is where people most often take a crooked path. A corporate proxy is set with the usual environment variables, and a private root certificate is attached with a separate variable. The temptation to switch certificate verification off instead is strong and understandable: it helps immediately and on every machine. But that is not a fix, it is the removal of protection - and with it goes the ability to notice a substitution, while the setting itself tends to migrate from local debugging into a build image and stay there for years.
It helps to collect the primary diagnostic commands once. Below are the version, sign-in status, general information and starting the protocol server. Any investigation starts with those: they answer what exactly is running, who is signed in and what state the agent is in. After that diagnosis proceeds from the symptom rather than from a guess, and the first thing it usually reveals is that the version running is not the one you had in mind.
It also helps to lay symptoms and the first check out in a table. Below is that map: command not found, a sign-in loop, a network error, endless permission requests, a missing tool, a broken shortcut in the terminal. Its value is that it turns diagnosis around: instead of asking what broke you answer which layer to check first.
| Symptom | What to check first |
|---|---|
| Command not found | The path variable and the install location |
| A sign-in loop | Browser availability, the credential store, the no-browser variable |
| A network error | Proxy variables, the root certificate, the service's domains |
| Endless permission requests | The configuration, allow and deny lists, administrator policy |
| A tool is missing | The server's tool list, plugin or skill scope |
| A broken shortcut | Terminal integration setup and the terminal reference |
One row deserves following to the end, because it shows the method. A network error in a corporate network almost always comes down to two different causes, and they are told apart by where the connection breaks. If the request never leaves or is refused at the address, the proxy variables are at fault: the process does not know whom to go out through. If the connection is established but fails during authenticity verification, the certificate is at fault: the outbound gateway signs the traffic with its own root, and that root is unknown to the process. Different causes are treated by different settings, and guessing here is especially wasteful, because every check costs a full startup cycle.
That table has a limit of applicability, and it is worth naming. It works while one layer is broken; with two simultaneous failures the first check leads to a correct cause but does not remove the symptom, and the investigation stalls. The practical sign of that case is a fix that changes the error message without removing it. What works then is not the table but a comparison of environments: the same run in a clean shell, on another machine or under another account shows what exactly your environment contributes, and the investigation narrows to the difference between two environments rather than to a sweep through settings.
The engineering conclusion is simple: most mysterious command-line problems are the environment. The path, the browser, the credential store, the proxy, the certificate, rights, plugin scope. The product meanwhile behaves exactly as designed, and hunting for a bug in it consumes the time that should have gone into checking the environment. The first step of any investigation is to record the version and the status, the second is to reproduce in a clean environment, and only the third is to suspect the tool.
The typical failures are predictable. Writing a protocol client without handling permission requests and getting a hang on the very first tool call. Switching certificate verification off instead of attaching the corporate one. Looking for a product bug where the path variable is at fault. Treating two simultaneous failures as one. And starting an investigation from guesses rather than from recording the version and the status.
agent --version
agent status
agent about
# The protocol server for your own client
agent acp