docs(usage): document AGENT_TTY_ACTIVE and AGENT_TTY_SESSION_ID child env variables

prmartinow · prmartinow · commit 3fd4363c906a · 2026-07-12T22:09:29.000+07:00
diff --git a/docs/USAGE.md b/docs/USAGE.md
@@ -233,6 +233,12 @@ agent-tty create --env PROMPT_EOL_MARK='%B%S%#%s%b' -- /bin/zsh
 
 A lone `'%'` does **not** restore the marker (zsh treats it as a prompt escape that expands to nothing); use `'%B%S%#%s%b'` for the styled default or `'%%'` for a plain percent. The default is applied at spawn time and is not stored in the manifest, so it does not appear in `inspect`, `list`, or `create --json` output. If your `~/.zshrc` assigns `PROMPT_EOL_MARK` it runs after the environment is imported and wins, so the marker can reappear — remove that line or set the value you want via `--env`.
 
+### Child Environment Injections
+
+The PTY spawn environment includes the following system variables:
+*   `AGENT_TTY_ACTIVE='true'`: Injected unconditionally into every child PTY process to indicate it is running within an active `agent-tty` session.
+*   `AGENT_TTY_SESSION_ID`: Propagated with the session's active ULID string (if a session ID is assigned), enabling child processes and custom wrapper scripts to query the current execution boundary.
+
 ## Exit Codes
 
 Every command exits with a stable code, so scripts can branch without parsing output. The `--json` error envelope carries the precise `error.code` when a command fails before producing a result. Commands that preserve an observable result for a failed predicate, such as timed-out `wait` and fail-fast `batch`, still emit a success envelope while exiting non-zero.
