Wuming 無名

Blog

Terminals in Your Pocket (3): Teaching Coding Agents to Knock

· Technology · English

Previous: An Architecture of Three Parts | Next: The Computer Decides Who Gets In | 中文版:让编程智能体学会敲门

The first two posts built the connection. A phone can see every tmux window on the computer and type into it. Stop there and you have a nicer SSH client, nothing more.

What changes how people work is the computer knocking on the phone’s door at the moment an agent needs a human. This post covers the three layers of that: knowing the agent is waiting, telling the phone, and delivering the answer safely.

Knowing it is waiting

From outside, an agent running in a terminal is a stream of characters. Telling “working” from “waiting for me” from “finished” can be done several ways, each with its own failure mode.

Watch the screen and guess. Look at the last few lines for “allow?” or “y/n”. It works until you switch agents, languages or versions, and the keywords stop matching.

Watch the process. An agent waiting for input is usually blocked on a terminal read with near-zero CPU. That separates “running” from “stopped”, but not “stopped to ask” from “stopped because done”.

Let the agent say so. The mainstream coding agents support hooks: a user-configured command that runs when the agent stops, asks a question or requests permission. This is the most reliable signal because it comes from the agent itself and carries structure: which session, what the question is, which options exist.

The system uses the third as the primary signal and the second as a fallback. The resident process ships a command that gets installed into the agent’s hook configuration. Whenever the agent stops, the hook runs, hands the event to the resident process, and the process decides whether to notify the phone. Process state covers tools with no hooks, such as a long test run or build that is worth a ping when it ends.

Hooks also expose something very useful: the tmux pane the agent lives in. With that, a notification can point at a specific window, and tapping it drops the person straight into that window instead of hunting through a dozen.

Putting the question on the lock screen

Notifications are nothing new. The detail is what goes in them.

The first version sent “an agent needs you”. The person then had to unlock the phone, open the app, find the window, read the question, and answer. By the end of that it was quicker to walk back to the desk.

The later version sends the question and the options. The agent asks “commit and push?” with the choices “yes” and “no, let me explain”; those two choices appear on the lock screen. Tap one and the answer goes back to the computer without unlocking the phone.

A push service sits in the middle here, one of the few places where a third party is involved, so the payload is trimmed: title, question, options. No code, no paths that might carry something sensitive. Anything more detailed, the phone fetches directly from the computer once the app is open.

Repeats get suppressed. Agents sometimes ask the same question twice within seconds, or one event arrives by two routes. The resident process deduplicates by session and content, so the same message is sent once within a few minutes.

Delivering the answer safely

This is the part of the system that needs the most care. Typing into a running terminal is executing an action on that computer. One wrong character turns “no” into “yes”, or lands a reply in a different program.

The rules are simple, and every one of them was added after something went wrong.

An answer must match a question that is still open. Each time the agent asks, the computer registers a one-time pending ask. The phone’s answer comes back with the ask’s id; if the id doesn’t match or the ask has expired, the answer is refused and the phone says “that question has passed, take a look”.

A question is answered once. The moment the first answer arrives, the pending ask is consumed. A second answer, even from the same person, is not typed. That stops double-taps from the phone and the desk answering at once, or from a network retry.

The program that asked must still be in that pane. Before typing, the computer checks that the process now running in the pane is the one that asked. If the agent has exited and the shell is back at a prompt, typing “y” would run a command called y. If the check fails, nothing is typed.

Answers are the offered options or plain text. The phone can’t construct arbitrary control sequences. Mapping an option to keystrokes happens on the computer.

Together these make a “one-time answer”. It matters more than it sounds: it means that a single tap on a lock screen can never turn into a misfire, whatever the timing.

From notifications to conversations

With a reliable two-way channel, the next step suggests itself: not just answering questions, but starting a task from the phone.

That layer is kept restrained. The phone has a task box: pick a computer, a directory and an agent, write a sentence, and the computer opens a new tmux window in that directory, starts the agent and hands it the sentence. Every step after that flows back through the hook mechanism as a readable conversation rather than raw terminal output. Wherever approval is needed there are two buttons, allow once and deny.

But it is still a tmux window. Want the raw output, switch to it. Back at the desk, keep typing in the same window. The conversation view is just another rendering of the same session.

One more small thing: frequently used instructions can be saved as templates with a few blanks, a branch name for instance. Fill them in on the phone and insert with two taps. It is these little things, added up, that make people actually willing to work from a phone.

Next, back to security: who gets to connect to your computer, and who decides.

The series

  1. Why Reach Your Computer From a Phone
  2. An Architecture of Three Parts
  3. Teaching Coding Agents to Knock (this post)
  4. The Computer Decides Who Gets In
  5. Troubleshooting Notes

Comments

  1. Loading comments…

Leave a comment

Plain text; links are fine. Comments with many links wait for review.