SubagentStop fires every turn — optimize stop gate

[AIOSAI]

Discovery (S172)

SubagentStop hook event fires on EVERY response turn, not just when Agent tool sub-agents complete. Claude Code internally creates an agent per turn with empty agent_type.

Payload differences:

• Real sub-agent: agent_type=general-purpose (or Explore, etc)
• Internal turn: agent_type empty

Current impact:

• subagent_stop_gate.py runs drone @git status every turn (~600ms wasted when no files modified)
• Piper speaks subagent stop gate every turn
• Checker itself works correctly — finds violations when files ARE modified

Potential optimization:

• Read agent_type from stdin — skip full git status + seedgo check when empty (internal turn)
• Or: only run when modified file count > 0 via a lighter check than drone subprocess
• Keep Piper speaking regardless so the trust layer stays visible

Not urgent — 600ms overhead is tolerable, checker is functional, no false positives.

[AIOSAI]

Investigation update (S186, 2026-06-02) — data captured, not fixing yet

Spent a full investigation pass on this with live monitoring. No code fix landed — this is deeper than the original framing and touches a blocking enforcement gate, so we're banking the findings here so next time starts from data, not from scratch. It is not breaking anything today; this is about getting sharper at managing the hooks before we change one.

---

1. Corrected mechanics (empirically verified, not assumed)

The handler on SubagentStop is subagent_gate.handle (src/aipass/hooks/apps/handlers/security/subagent_gate.py). It reads only cwd from the payload today — it does not read agent_type.

Authoritative Claude Code schema (docs) + live capture confirm the discriminator the original issue guessed at is real:

• agent_type — the sub-agent's name (Explore, general-purpose, …). Empty on internal/main turns.
• agent_id — present only when the hook fires inside a real sub-agent call.

Captured real sub-agent payload (Explore):

{"event":"SubagentStop","hook":"subagent_stop_gate",
 "agent_type":"Explore","agent_id":"aa309a4002bc88a9...",
 "exit_code":0,"elapsed_ms":1440.2,"cwd":".../devpulse"}

cwd is the parent's dir (devpulse), not the sub-agent's — so cwd cannot distinguish who fired. agent_type/agent_id is the only reliable signal.

2. What fires when (this corrects an earlier wrong conclusion in this session)

Both happen — verified in the prax monitor:

• A real sub-agent finishing → SubagentStop ... agent=Explore
• An internal/main turn → SubagentStop ... agent=main (empty agent_type), with no sub-agent running:

  21:11:44 [DRONE] 0 file(s) changed under src/aipass/devpulse
  21:11:44 [HOOKS] SubagentStop.subagent_stop_gate agent=main exit=0 out=0b 1218ms
  21:20:42 [HOOKS] SubagentStop.subagent_stop_gate agent=main exit=0 out=0b 1212ms
  

• A main turn ending fires the separate Stop event (Stop.stop_sound agent=main).

So the original S172 premise holds: SubagentStop fires on internal turns with empty agent_type, and that work is wasted (runs drone @git status, finds nothing, ~1.2s). Claude Code's internal per-turn agent is real.

3. The real cost

From hooks/logs/engine.jsonl elapsed_ms:

• ~1.0–1.5s on a clean/internal fire (just the drone @git status subprocess).
• up to ~16s when files were modified — because it runs drone @seedgo checklist <file> as a separate subprocess per file.

4. Why this is NOT a simple fix — the deeper problem

subagent_gate is a blocking gate: on violations it returns exit 2 / {"decision":"block"}. Two structural issues:

1. Mis-scoped audit. It checks every modified .py in the whole branch dirty tree on every fire — it does not check whether the firing sub-agent actually touched anything. Failure mode: parent has a half-finished file with a violation → spawns a read-only Explore agent → Explore finishes → gate sees the parent's unrelated WIP → blocks Explore, telling it to "fix violations" in a file it never touched. (Same risk applies to agent=main internal fires blocking on WIP.)
2. Seedgo isn't the problem — it's correctly checking files; it's being pointed at the wrong set (whole dirty tree vs. the sub-agent's actual diff).

5. Open question that gates any fix (BLAST RADIUS — unresolved)

We have never observed a real block. Every captured fire is exit 0. Before changing a gate that can return decision:block, we must deliberately trigger a block on SubagentStop and watch what Claude Code does to the sub-agent (does it loop and keep working? surface the reason to the parent? error?). That experiment is the thing that unlocks a safe change. Do not change the gate blind.

6. Candidate directions (NOT decided — for next session, with @hooks who owns this engine)

• (a) Skip the heavy audit when agent_type is empty (internal/main turns) — the original proposal, now empirically justified. Kills the per-internal-turn waste and removes the WIP-block risk for internal fires.
• (b) Scope the audit to the sub-agent's actual diff, not the whole branch dirty tree (the real correctness fix).
• (c) Advisory instead of block for the stop-gate (reconsider whether post-hoc blocking is the right enforcement point at all).
• Keep Piper on every fire (trust layer) regardless.

7. Instrumentation added this session (diagnostic — recommend @hooks adopt permanently)

The engine logged only a summary; agent_type/agent_id flowed through dispatch() into the handler but was never written to either sink (engine.jsonl or the prax system_logger that feeds the monitor). Added a one-line capture in engine.py dispatch() so both sinks record agent_type/agent_id per fire (monitor now shows agent=main vs agent=Explore). This is how we saw any of the above — recommend @hooks make it permanent with tests. (Currently a local, uncommitted diagnostic edit.)

---

Bottom line: premise confirmed (fires on internal turns, wasted work), real problem is bigger than perf (mis-scoped blocking audit), and the blast radius is unverified (never seen a block). Parked until we can pair with @hooks and run the block experiment. Not urgent, not breaking — pure hook-management maturity.