use super::*;
pub(crate) enum TrapSelf {
Agent(String),
Session(String),
}
pub(crate) fn resolve_trap(marker: &str) -> Result<TrapSelf> {
let marker = marker.trim();
validate_trap_marker(marker)?;
let session_id = resolve_env_session()?;
let main_jsonl = locate_session_jsonl(&session_id).ok_or_else(|| {
anyhow!(
"@trap: cannot locate the calling session {session_id}.jsonl under the projects root"
)
})?;
let main_hit = bash_command_carries_trap(&main_jsonl, marker);
let mut subagent_hits: Vec<String> = Vec::new();
for sub in crate::subagent::subagent_transcript_files(&main_jsonl)? {
if bash_command_carries_trap(&sub, marker) {
subagent_hits.push(crate::subagent::session_id_from_path(&sub));
}
}
match subagent_hits.len() {
1 => Ok(TrapSelf::Agent(subagent_hits.remove(0))),
0 if main_hit => {
eprintln!(
"csift: note: @trap:{marker} resolved to the TOP-LEVEL session {session_id} - \
the marker was carried by the MAIN transcript, so you are NOT a subagent in \
this lane. `@main` answers this directly with no race; @trap is for \
subagents, which cannot name themselves."
);
Ok(TrapSelf::Session(session_id))
}
0 => bail!(
"@trap: marker `{marker}` not found in a `csift` shell command (Bash / PowerShell) of \
the calling session. MOST LIKELY you are the TOP-LEVEL thread: use `@main` \
(env-based, no race). That is the answer to your question. \
Otherwise, check that the marker appears LITERALLY in THIS csift invocation (no \
shell variable / concatenation, and the command must actually run `csift`) - a \
non-literal marker misses in every lane. \
LAST, to confirm the lane: re-run this EXACT command with the SAME marker as a NEW, \
SEPARATE shell invocation. The main conversation's record is an async flush of the \
completed assistant message, landing ~1-3.4s after the tool was dispatched, so a \
first use races it; the retry reads the by-then-landed record. A second attempt \
inside the SAME shell script does NOT count - it runs inside that same unlanded \
window, whose width is invisible from inside the script. A fresh marker restarts \
the race."
),
n => bail!(
"@trap: marker `{marker}` is AMBIGUOUS — it matched {n} subagents. Use a fresher, \
more random marker (it must be unique within the conversation)."
),
}
}
pub struct WhoNode {
pub session_id: String,
pub is_subagent: bool,
pub parent_session_id: String,
pub depth: Option<usize>,
pub path: Option<PathBuf>,
}
pub fn resolve_trap_who(marker: &str) -> Result<Vec<WhoNode>> {
let root = resolve_env_session()?;
let main_jsonl = locate_session_jsonl(&root);
match resolve_trap(marker)? {
TrapSelf::Session(session_id) => {
let path = locate_session_jsonl(&session_id);
Ok(vec![WhoNode {
parent_session_id: session_id.clone(),
session_id,
is_subagent: false,
depth: None,
path,
}])
}
TrapSelf::Agent(agent_id) => {
let nodes = main_jsonl
.as_deref()
.and_then(|m| crate::subagent::build_topology(m, false).ok())
.unwrap_or_default();
let sub_files = main_jsonl
.as_deref()
.and_then(|m| crate::subagent::subagent_transcript_files(m).ok())
.unwrap_or_default();
let locate_sub = |hex: &str| {
sub_files
.iter()
.find(|p| crate::subagent::session_id_from_path(p) == hex)
.cloned()
};
let mut chain: Vec<WhoNode> = Vec::new();
let mut cur = Some(agent_id);
while let Some(hex) = cur {
if chain.iter().any(|n| n.session_id == hex) {
break;
}
let node = nodes.iter().find(|n| n.agent_id == hex);
let depth = node.map(|n| n.depth);
let next = node.and_then(|n| n.parent_agent_id.clone());
let path = locate_sub(&hex);
chain.push(WhoNode {
session_id: hex,
is_subagent: true,
parent_session_id: root.clone(),
depth,
path,
});
cur = next;
}
chain.push(WhoNode {
parent_session_id: root.clone(),
session_id: root,
is_subagent: false,
depth: None,
path: main_jsonl,
});
Ok(chain)
}
}
}
pub(crate) const RESERVED_EXAMPLE_MARKERS: &[&str] = &["JollyShinyBrook4283"];
pub(crate) fn validate_trap_marker(marker: &str) -> Result<()> {
let guidance = "@trap needs a marker you INVENT one-shot, right now, by hand: EXACTLY 3 \
imaginative, CONTEXT-INDEPENDENT CamelCase words (each 1 uppercase + >=2 \
lowercase) + 4 non-trivial digits. The shape looks like `JollyShinyBrook4283`, \
but that literal is the RESERVED doc example and is itself refused — pick your \
OWN. Put it VERBATIM in this csift command (no shell variable / concatenation), \
and never generate it with a script. Rejected: not exactly 3 words, \
single-letter or ALLCAPS \"words\", missing or !=4 trailing digits, trivial \
digits (1111 / 1234 / 9876 / 1357 / 2468 ...), or the reserved doc example.";
if marker.is_empty() {
bail!("{guidance}");
}
if RESERVED_EXAMPLE_MARKERS.contains(&marker) {
bail!(
"@trap: marker `{marker}` is the RESERVED documentation example — the SKILL / --help / \
SPEC print it next to `csift`, so quoting the doc self-matches it and every agent that \
copies it clashes into ambiguity. csift always refuses it. {guidance}"
);
}
if !marker.is_ascii() || marker.len() < 13 {
bail!("@trap: marker `{marker}` is malformed. {guidance}");
}
let (words, digits) = marker.split_at(marker.len() - 4);
if digits.len() != 4 || !digits.bytes().all(|b| b.is_ascii_digit()) {
bail!("@trap: marker `{marker}` must END with exactly 4 digits. {guidance}");
}
match camel_words(words) {
Some(w) if w.len() == 3 => {}
_ => bail!(
"@trap: marker `{marker}` must be EXACTLY 3 CamelCase words (each: 1 uppercase + >=2 \
lowercase) before the 4 digits. {guidance}"
),
}
if is_trivial_4_digits(digits) {
bail!(
"@trap: the 4 digits `{digits}` are a trivial run — pick non-sequential random \
digits. {guidance}"
);
}
Ok(())
}
pub(crate) fn camel_words(s: &str) -> Option<Vec<&str>> {
let b = s.as_bytes();
let mut words: Vec<&str> = Vec::new();
let mut i = 0;
while i < b.len() {
if !b[i].is_ascii_uppercase() {
return None;
}
let start = i;
i += 1;
let mut lower = 0;
while i < b.len() && b[i].is_ascii_lowercase() {
i += 1;
lower += 1;
}
if lower < 2 {
return None;
}
words.push(&s[start..i]);
}
(!words.is_empty()).then_some(words)
}
pub(crate) fn is_trivial_4_digits(d: &str) -> bool {
let v: Vec<i32> = d.bytes().map(|b| i32::from(b - b'0')).collect();
let s1 = v[1] - v[0];
let s2 = v[2] - v[1];
let s3 = v[3] - v[2];
s1 == s2 && s2 == s3 && (-2..=2).contains(&s1)
}
pub(crate) fn locate_session_jsonl(id: &str) -> Option<PathBuf> {
let root = projects_root().ok()?;
let fname = format!("{id}.jsonl");
if let Ok(cwd) = std::env::current_dir() {
let c = root.join(encode_cwd(&cwd)).join(&fname);
if c.is_file() {
return Some(c);
}
}
for pd in all_project_dirs().ok()? {
let c = pd.dir.join(&fname);
if c.is_file() {
return Some(c);
}
}
None
}
pub(crate) fn bash_command_carries_trap(path: &Path, marker: &str) -> bool {
let Ok(Some(mmap)) = crate::parse::mmap_bytes(path) else {
return false;
};
let bytes: &[u8] = &mmap;
if memchr::memmem::find(bytes, marker.as_bytes()).is_none() {
return false;
}
let mut found = false;
let _ = crate::parse::scan_lines_bytes(bytes, |line| {
if found {
return;
}
if let Ok(Some(rec)) = crate::parse::parse_line(line) {
if let Some(blocks) = rec.blocks() {
for b in blocks {
if let crate::model::Block::ToolUse {
name: Some(n),
input: Some(inp),
..
} = b
{
if (n == "Bash" || n == "PowerShell")
&& inp
.get("command")
.and_then(serde_json::Value::as_str)
.is_some_and(|c| c.contains(marker) && c.contains("csift"))
{
found = true;
}
}
}
}
}
});
found
}