There is nothing for you to configure on this page. There is no hooks screen, there is no hooks file of yours, there is no preference to turn this on or off.This is how it works documentation, for anyone who wants to understand where the approvals inbox comes from. If you just want to use the product, skip it.
The problem
An agent running loose is a process that decides on its own. It reads what it wants, writes what it wants, and you find out afterwards — by reading the diff, or by not reading it. For a gate to exist, someone has to be told before each tool runs, and has to be able to hold execution until the answer arrives. You cannot do that by scraping the screen: by the time the text shows up in the terminal, the command has already run. Claude Code and Codex have a mechanism for this — hooks. TYBA uses that mechanism.What TYBA does
Every time an agent session starts, TYBA injects a hooks configuration into the agent and opens a local channel to receive the events.1
It builds the configuration
A handful of events pointing at a single command: TYBA’s own binary, in a special mode (
_hook).2
It injects it into the agent
Claude Code — a
hooks.json in a private directory for the session, passed with --settings.Codex — no file: the hooks go as --config on the command line, each with a hash that Codex checks so it can accept them without asking you.3
It opens the channel
A local socket — AF_UNIX on macOS and Linux, a named pipe on Windows, because a unix socket does not cross the jail there. The path reaches the agent in the
TYBA_HOOK_SOCKET variable.4
The agent calls back
Before using a tool, the agent runs the hook command. It re-executes TYBA’s binary, which reads the socket from the variable and hands the event to the app.
The events
On Codex there is also
PermissionRequest, which is how it asks for permission.
Why PreToolUse is the whole product
When the agent is about to use a tool, the hook fires first and hangs there waiting for an answer. That wait is what makes room for a decision to exist.
TYBA classifies the action as green, yellow or red. Green comes back allowed immediately, without you seeing it. Yellow and red block the hook and become an inbox item — the agent is literally stopped mid-call, because the hook process has not returned yet.
You answer, the hook returns allowed or denied, and the agent moves on or takes the refusal.
The
PreToolUse timeout is 86,400 seconds — 24 hours. It is not excessive: it is the number that says “wait for the user however long it takes”. The other events, which only report, get 60 seconds.Meanwhile, Claude Code shows “Waiting for approval in TYBA…” on its own screen.Where the session status comes from
From the same channel. The hook events become status directly:
This is structured data, not text scraped off the screen. No heuristic looks at what the agent drew in the terminal to guess whether it is done.
OSC 133 does exist, but it serves something else: detecting that an agent is running in a plain shell, so the composer can appear. That is a display hint, never authorization — and a shell has no gate.
This is not the repository consent
An easy confusion, and the two have nothing to do with each other:
The hooks are internal machinery: without them there is no gate, so there is no button to turn them off — turning them off would remove the only thing holding the agent back.
The
.tyba/config.toml is third-party content, it came along with a git clone, and that is why it counts for nothing until you approve it. The rules are in Repository configuration.
When the channel breaks
Fail-closed. A session that dies with pending requests has all of them denied; a broken channel denies. There is no path where an infrastructure failure turns into permission — the same principle described in Risk classification.See also
Risk classification
What
PreToolUse does with each command.Agent over SSH
What happens when the hook does not exist.