ππΌββοΈ The blackboard for coding agents - agentic development environment for claude code, codex, cursor, opencode, grok and more.
Rust adeai-agentsclaudeclaude-codecodexcursorgeminigrokopencodespec-driven-developmentvibe-codingvim
//! Agent-reported lifecycle status, written by agent hooks and read by the TUI.
//!
//! Agents that support lifecycle hooks are configured to invoke `agtx hook --env
//! <agent>` on session/turn/tool events. That subcommand parses the hook's JSON
//! payload from stdin and writes `.agtx/status/{task_id}.json` inside the
//! worktree. The board's session-refresh thread reads that file instead of
//! guessing liveness from `tmux capture-pane` output.
//!
//! Which agents, and where their config goes, is [`HookConfigKind`]; every one
//! of them is project-local, so registration lives and dies with the worktree.
//!
//! Two things here are per-agent: [`map_hook_event`], because the vocabularies
//! differ, and where the event name comes from ([`super::spec::HookEventSource`]).
//! Merging, staleness, the `Blocked` guard and the atomic write are shared.
//!
//! This module is deliberately free of tmux, database and TUI types so the event
//! mapping and staleness rules can be unit-tested in isolation β the same
//! precedent as `src/tui/dep_graph.rs`.
use crate::agent::spec::HookConfigKind;
use anyhow::Result;
use serde::{Deserialize, Serialize};
use std::io::Read;
use std::path::{Path, PathBuf};
/// Directory (relative to a worktree) holding per-task status files.
pub const STATUS_DIR: &str = ".agtx/status";
/// A `Working` record older than this is distrusted and the caller falls back to
/// the pane-hash heuristic. Covers an agent killed without firing `SessionEnd`
/// and an agent build that dropped an event. Only `Working` decays β a blocked
/// agent stays blocked indefinitely.
pub const HOOK_STALE_SECS: i64 = 300;
/// How long a `Blocked` record is protected from being overwritten by a
/// `Working` event. An agent can emit its tool heartbeat for the very tool it is
/// requesting permission for, which would otherwise clear the block instantly.
pub const BLOCKED_GUARD_SECS: i64 = 2;
/// Maximum stdin payload accepted from a hook invocation.
pub const MAX_PAYLOAD_BYTES: usize = 64 * 1024;
/// Longest `message` / `tool` string retained; hook payloads are untrusted input
/// and this text reaches the TUI and orchestrator notifications.
const MAX_FIELD_CHARS: usize = 512;
/// What the agent last told us about itself.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
pub struct AgentHookStatus {
/// Unix seconds when the event was recorded.
pub ts: i64,
pub state: HookState,
/// Agent-reported session id, for future resume-by-id.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub session_id: Option<String>,
/// Path to the agent's own transcript, when reported.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub transcript_path: Option<String>,
/// The permission prompt or question text, when the agent is Blocked.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub message: Option<String>,
/// Tool name from the last PreToolUse β heartbeat detail.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub tool: Option<String>,
/// Which agent wrote this record.
pub agent: String,
}
#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq)]
#[serde(rename_all = "snake_case")]
pub enum HookState {
/// Turn in progress, or a tool is running.
Working,
/// Stopped, awaiting a permission decision or an answer from the user.
Blocked,
/// Turn ended; the composer is idle and accepting input.
Waiting,
/// Session terminated.
Ended,
}
/// Map one agent's lifecycle event name to a state.
///
/// `None` means the event carries no transition and the stored record is left
/// alone. An event from another agent's vocabulary also returns `None`: the kind
/// is a parameter, not a fallback chain, so a registration typo cannot resolve
/// against the wrong agent's arm. `Stop` means "turn over" to four agents while
/// Gemini's equivalent is `AfterAgent` and Cursor's is lowercase `stop`.
///
/// Each arm names the version it was read from.
pub fn map_hook_event(kind: HookConfigKind, event: &str) -> Option<HookState> {
use HookConfigKind::*;
match kind {
// claude 2.1.247.
ClaudeSettings => match event {
"SessionStart" | "UserPromptSubmit" | "PreToolUse" => Some(HookState::Working),
// `Notification` counts as Blocked only because the registration
// pins `matcher: "permission_prompt"`; unscoped it also fires for
// `idle_prompt`. Same arrangement as grok's, and the scoping lives
// in [`hook_events`] rather than here because the payload never
// reaches this function.
"PermissionRequest" | "Notification" => Some(HookState::Blocked),
"Stop" | "StopFailure" => Some(HookState::Waiting),
"SessionEnd" => Some(HookState::Ended),
_ => None,
},
// codex-cli 0.144.5. Claude's schema minus `SessionEnd` (window-gone
// detection covers Exited) and `Notification`.
CodexHooksJson => match event {
"SessionStart" | "UserPromptSubmit" | "PreToolUse" | "PostToolUse" => {
Some(HookState::Working)
}
"PermissionRequest" => Some(HookState::Blocked),
"Stop" => Some(HookState::Waiting),
_ => None,
},
// gemini-cli 0.46.0. Its own vocabulary: the turn boundary is
// `BeforeAgent`/`AfterAgent` and the tool heartbeat is `BeforeTool`.
// `Notification` fires on a ToolPermission alert and carries `message`.
GeminiSettings => match event {
"SessionStart" | "BeforeAgent" | "BeforeTool" | "AfterTool" => {
Some(HookState::Working)
}
"Notification" => Some(HookState::Blocked),
"AfterAgent" => Some(HookState::Waiting),
"SessionEnd" => Some(HookState::Ended),
_ => None,
},
// cursor-agent 2026.08.25. camelCase, and no event for a human-blocking
// prompt: the `beforeShellExecution` family are policy gates that decide,
// not prompts that wait. Cursor never reports Blocked.
CursorHooksJson => match event {
"sessionStart" | "beforeSubmitPrompt" | "preToolUse" | "postToolUse" => {
Some(HookState::Working)
}
"stop" => Some(HookState::Waiting),
"sessionEnd" => Some(HookState::Ended),
_ => None,
},
// grok 1.0.5. Config and payload disagree about spelling: hooks are
// registered under `PreToolUse` and arrive as `"pre_tool_use"`, so both
// must map β hence `squash`.
//
// `notification` counts as Blocked only because the registration pins
// `matcher: "permission_prompt"`; unscoped it also fires for
// `idle_prompt` and `task_complete`.
GrokHooksJson => match squash(event).as_str() {
"sessionstart" | "userpromptsubmit" | "pretooluse" => Some(HookState::Working),
"notification" => Some(HookState::Blocked),
"stop" | "stopfailure" | "stopcancelled" => Some(HookState::Waiting),
"sessionend" => Some(HookState::Ended),
_ => None,
},
// agy 1.1.21. Five events, no session lifecycle and no permission event.
// `PreInvocation` fires before each model call β its nearest thing to a
// turn start; `Stop` ends the execution loop, not the session.
AntigravityHooksJson => match event {
"PreInvocation" | "PostInvocation" | "PostToolUse" => Some(HookState::Working),
"Stop" => Some(HookState::Waiting),
_ => None,
},
}
}
/// Lowercase and drop underscores, so one arm accepts both spellings grok uses
/// for an event: `PreToolUse` when registered, `pre_tool_use` when reported.
fn squash(event: &str) -> String {
event.chars().filter(|c| *c != '_').flat_map(char::to_lowercase).collect()
}
/// The events agtx registers for one agent.
///
/// The write half of the pair whose read half is [`map_hook_event`]. A name
/// listed here but not mapped there is a hook that fires and reports nothing, so
/// `tests/hook_status_tests.rs` asserts the two agree in both directions.
///
/// The second element is the event's tool matcher, or `None` when the event is
/// not tool-scoped.
pub fn hook_events(kind: HookConfigKind) -> &'static [(&'static str, Option<&'static str>)] {
use HookConfigKind::*;
match kind {
ClaudeSettings => &[
// Liveness: a turn started, or a tool is about to run (heartbeat).
("SessionStart", None),
("UserPromptSubmit", None),
("PreToolUse", Some("*")),
// Blocked: the agent is stopped waiting on a human.
("PermissionRequest", Some("*")),
// Scoped for the same reason grok's is: `Notification` is not one
// event. Measured against Claude Code 2.1.263, it carries a
// `notification_type` β `permission_prompt` ("Claude needs your
// permission") and `idle_prompt` ("Claude is waiting for your
// input"), the latter fired ~66s after a turn simply ends.
// Unscoped, an agent that has simply finished its turn would report
// Blocked, and an agent-reported Blocked fires the stuck-task path
// *immediately*, with no settle window β so a caller would interrupt
// an agent that is merely quiet. Claude honours the matcher here
// (verified): with it, an idle turn produces no event at all.
("Notification", Some("permission_prompt")),
// Turn over / session over.
("Stop", None),
("StopFailure", None),
("SessionEnd", None),
],
CodexHooksJson => &[
("SessionStart", None),
("UserPromptSubmit", None),
("PreToolUse", Some("*")),
("PostToolUse", Some("*")),
("PermissionRequest", Some("*")),
("Stop", None),
],
GeminiSettings => &[
("SessionStart", Some("*")),
("BeforeAgent", Some("*")),
("BeforeTool", Some("*")),
("AfterTool", Some("*")),
("Notification", Some("*")),
("AfterAgent", Some("*")),
("SessionEnd", Some("*")),
],
CursorHooksJson => &[
("sessionStart", None),
("beforeSubmitPrompt", None),
("preToolUse", None),
("postToolUse", None),
("stop", None),
("sessionEnd", None),
],
// Registered in PascalCase, reported in snake_case; see the grok arm of
// `map_hook_event`.
GrokHooksJson => &[
("SessionStart", None),
("UserPromptSubmit", None),
("PreToolUse", Some("*")),
// Scoped: unmatched, this also fires on idle and task-complete.
("Notification", Some("permission_prompt")),
("Stop", None),
("StopFailure", None),
("StopCancelled", None),
("SessionEnd", None),
],
// No `PreToolUse`, deliberately: antigravity makes that hook's
// `decision` output *required* and reads anything else as a refusal, so
// subscribing blocks every tool call. Answering `"allow"` would make a
// liveness reporter into a permission granter. `PostToolUse` carries the
// heartbeat instead and wants exactly the `{}` this hook prints.
AntigravityHooksJson => &[
("PreInvocation", None),
("PostInvocation", None),
("PostToolUse", Some("*")),
("Stop", None),
],
}
}
/// Path to a task's status file inside its worktree.
pub fn status_path(worktree: &Path, task_id: &str) -> PathBuf {
worktree.join(STATUS_DIR).join(format!("{}.json", task_id))
}
/// Read and parse a task's status record.
///
/// Returns `None` when the file is missing, unparseable, or holds a `Working`
/// record older than [`HOOK_STALE_SECS`] β in every one of those cases the
/// caller should fall back to the pane-hash heuristic.
pub fn read_status(worktree: &Path, task_id: &str, now: i64) -> Option<AgentHookStatus> {
let raw = std::fs::read_to_string(status_path(worktree, task_id)).ok()?;
let status: AgentHookStatus = serde_json::from_str(&raw).ok()?;
if status.state == HookState::Working && now.saturating_sub(status.ts) > HOOK_STALE_SECS {
return None;
}
Some(status)
}
/// Write a status record atomically: temp file in the same directory, then rename.
///
/// The rename is what makes a concurrent reader see either the old record or the
/// new one, never a half-written file.
pub fn write_status(worktree: &Path, task_id: &str, status: &AgentHookStatus) -> Result<()> {
let path = status_path(worktree, task_id);
if let Some(parent) = path.parent() {
std::fs::create_dir_all(parent)?;
}
// Include the pid so two hooks racing on the same task can't truncate each
// other's temp file before either rename lands.
let tmp = path.with_extension(format!("tmp{}", std::process::id()));
std::fs::write(&tmp, serde_json::to_string(status)?)?;
std::fs::rename(&tmp, &path)?;
Ok(())
}
/// Decide the record to persist given an incoming event and whatever is stored.
///
/// Returns `None` when the event should not change the stored record. Two rules:
/// an event with no mapping *for this agent* is ignored, and a `Working` event is
/// dropped while a fresh `Blocked` record stands (see [`BLOCKED_GUARD_SECS`]).
pub fn merge_event(
previous: Option<&AgentHookStatus>,
kind: HookConfigKind,
event: &str,
now: i64,
agent: &str,
session_id: Option<String>,
transcript_path: Option<String>,
message: Option<String>,
tool: Option<String>,
) -> Option<AgentHookStatus> {
let state = map_hook_event(kind, event)?;
if state == HookState::Working {
if let Some(prev) = previous {
if prev.state == HookState::Blocked && now.saturating_sub(prev.ts) <= BLOCKED_GUARD_SECS
{
return None;
}
}
}
// Carry forward identity fields the current event didn't report, so a `Stop`
// payload doesn't erase the session id learned at `SessionStart`.
let prev_session = previous.and_then(|p| p.session_id.clone());
let prev_transcript = previous.and_then(|p| p.transcript_path.clone());
Some(AgentHookStatus {
ts: now,
state,
session_id: session_id.or(prev_session),
transcript_path: transcript_path.or(prev_transcript),
// `message` is only meaningful for the event that produced it.
message: if state == HookState::Blocked {
message.map(|m| truncate(&m))
} else {
None
},
tool: tool.map(|t| truncate(&t)),
agent: agent.to_string(),
})
}
fn truncate(s: &str) -> String {
let cleaned: String = s
.chars()
.filter(|c| !c.is_control() || *c == '\n' || *c == '\t')
.collect();
let trimmed = cleaned.trim();
if trimmed.chars().count() <= MAX_FIELD_CHARS {
return trimmed.to_string();
}
trimmed.chars().take(MAX_FIELD_CHARS).collect()
}
/// Fields lifted from a hook's JSON payload. Every field is optional: agents
/// disagree about which they send, and a missing field must never be fatal.
///
/// The aliases carry the two agents that do not send `snake_case`.
#[derive(Debug, Default, Deserialize)]
struct HookPayload {
/// Grok spells this `hookEventName`, with a snake_case value.
#[serde(alias = "hookEventName")]
hook_event_name: Option<String>,
#[serde(alias = "sessionId")]
session_id: Option<String>,
/// `conversationId` is antigravity's session identifier.
#[serde(alias = "conversationId")]
conversation_id: Option<String>,
#[serde(alias = "transcriptPath")]
transcript_path: Option<String>,
message: Option<String>,
#[serde(alias = "toolName")]
tool_name: Option<String>,
/// Antigravity's `PreToolUse` payload nests the tool under `toolCall.name`.
#[serde(alias = "toolCall")]
tool_call: Option<ToolCall>,
}
#[derive(Debug, Default, Deserialize)]
struct ToolCall {
name: Option<String>,
}
/// Environment variables identifying the task a hook is reporting about, set on
/// the tmux window by `create_window`.
pub const ENV_TASK_ID: &str = "AGTX_TASK_ID";
pub const ENV_WORKTREE: &str = "AGTX_WORKTREE";
/// Entry point for `agtx hook --env <agent> [--event <Name>]` (preferred) or the
/// legacy `agtx hook <task-id> <worktree> [agent]`.
///
/// `--env` reads the task from the process environment, so one registered command
/// serves every task β necessary under `skip_worktree`, where all of them share
/// the project's agent config.
///
/// `--event` names the firing event for an agent whose payload does not
/// ([`super::spec::HookEventSource::Argv`]). The payload wins when it has one, so
/// an agent that starts sending an event name is not shadowed by a stale argv
/// value.
///
/// If the task variables are absent the hook exits silently, so a registration
/// stays inert outside agtx.
///
/// Always succeeds. A hook that reports an error can break the agent's turn, so
/// every failure path is a silent no-op after the mandatory `{}` on stdout.
pub fn run_hook_cli(args: &[String]) -> Result<()> {
// Claude-compatible permission hooks fail closed on empty stdout, so this
// must be printed before any early return.
println!("{{}}");
// Lifted out first so the positional parsing below is unaffected.
let mut argv_event: Option<String> = None;
let mut args: Vec<String> = args.to_vec();
if let Some(i) = args.iter().position(|a| a == "--event") {
argv_event = args.get(i + 1).cloned();
args.drain(i..=(i + 1).min(args.len() - 1));
}
let args = &args[..];
let from_env = args.first().map(String::as_str) == Some("--env");
let (task_id, worktree, agent);
if from_env {
// A backgrounded agent task runs in a worker that inherited the pane's
// env, so these would name a task it is not running in.
if std::env::var_os("CLAUDE_JOB_DIR").is_some() {
return Ok(());
}
let (Ok(t), Ok(w)) = (std::env::var(ENV_TASK_ID), std::env::var(ENV_WORKTREE)) else {
return Ok(());
};
if t.is_empty() || w.is_empty() {
return Ok(());
}
task_id = t;
worktree = w;
agent = args.get(1).cloned().unwrap_or_else(|| "claude".to_string());
} else {
let (Some(t), Some(w)) = (args.first(), args.get(1)) else {
return Ok(());
};
task_id = t.clone();
worktree = w.clone();
agent = args.get(2).cloned().unwrap_or_else(|| "claude".to_string());
}
let (task_id, worktree, agent) = (task_id.as_str(), worktree.as_str(), agent.as_str());
let mut buf = Vec::new();
if std::io::stdin()
.take(MAX_PAYLOAD_BYTES as u64)
.read_to_end(&mut buf)
.is_err()
{
return Ok(());
}
record_hook_event(task_id, worktree, agent, argv_event.as_deref(), &buf);
Ok(())
}
/// Everything after the argv and stdin plumbing: decide what the payload means
/// and persist it. Split out so tests can supply a payload without real stdin.
///
/// `argv_event` names the firing event for an agent whose payload does not carry
/// one; it is consulted only when the payload has no `hook_event_name`.
pub fn record_hook_event(
task_id: &str,
worktree: &str,
agent: &str,
argv_event: Option<&str>,
payload: &[u8],
) {
// An unknown agent name β a typo, or a spec removed under a live worktree β
// must not borrow another agent's vocabulary. See `map_hook_event`.
let Some(kind) = crate::agent::spec(agent).and_then(|s| s.hook_config) else {
return;
};
let payload: HookPayload = serde_json::from_slice(payload).unwrap_or_default();
// Payload first: an agent that sends an event name outranks the registration.
let Some(event) = payload
.hook_event_name
.as_deref()
.or(argv_event)
.filter(|e| !e.is_empty())
else {
return;
};
let worktree = Path::new(worktree);
let now = chrono::Utc::now().timestamp();
let previous = read_status(worktree, task_id, now);
if let Some(next) = merge_event(
previous.as_ref(),
kind,
event,
now,
agent,
payload.session_id.or(payload.conversation_id),
payload.transcript_path,
payload.message,
payload.tool_name.or(payload.tool_call.and_then(|t| t.name)),
) {
let _ = write_status(worktree, task_id, &next);
}
}