Context
During the peer review of PR #187 (SDK optimization), several minor findings were deferred as acceptable trade-offs for v1. Tracking here for future reference.
Deferred Items
#3 — TeammateIdle TOCTOU on task reads
File: teammate_idle.py:249
Issue: get_task_list() reads from disk; if multiple agents complete simultaneously, the hook may see stale task state and emit a false stall alert.
Assessment: Practically impossible due to sequencing (TaskUpdate completes before agent goes idle). False alerts are self-correcting via imPACT triage.
Revisit when: False stall alerts observed in production use.
#4 — Shutdown via systemMessage is indirect
File: teammate_idle.py:274-279
Issue: Hooks can't call SendMessage directly, so force-shutdown at 5 idles instructs orchestrator via systemMessage. If orchestrator context is near capacity, message may be missed.
Assessment: Architecturally correct. Unfixable without SDK changes (hooks can't call model tools). Manual /PACT:wrap-up is the fallback.
Revisit when: SDK adds hook-to-model tool bridge.
#7 — Read-modify-write atomicity
File: teammate_idle.py:154-170
Issue: read_idle_counts and write_idle_counts don't hold lock across the full R-M-W cycle. Concurrent idle events for different teammates could theoretically lose an increment.
Assessment: Harmless in practice — shutdown happens one event later. Same-teammate concurrent idles can't occur.
Fix: Hold fcntl lock across entire read-modify-write cycle.
Revisit when: Concurrent idle count corruption observed.
Reference
Context
During the peer review of PR #187 (SDK optimization), several minor findings were deferred as acceptable trade-offs for v1. Tracking here for future reference.
Deferred Items
#3 — TeammateIdle TOCTOU on task reads
File:
teammate_idle.py:249Issue:
get_task_list()reads from disk; if multiple agents complete simultaneously, the hook may see stale task state and emit a false stall alert.Assessment: Practically impossible due to sequencing (TaskUpdate completes before agent goes idle). False alerts are self-correcting via imPACT triage.
Revisit when: False stall alerts observed in production use.
#4 — Shutdown via systemMessage is indirect
File:
teammate_idle.py:274-279Issue: Hooks can't call SendMessage directly, so force-shutdown at 5 idles instructs orchestrator via systemMessage. If orchestrator context is near capacity, message may be missed.
Assessment: Architecturally correct. Unfixable without SDK changes (hooks can't call model tools). Manual
/PACT:wrap-upis the fallback.Revisit when: SDK adds hook-to-model tool bridge.
#7 — Read-modify-write atomicity
File:
teammate_idle.py:154-170Issue:
read_idle_countsandwrite_idle_countsdon't hold lock across the full R-M-W cycle. Concurrent idle events for different teammates could theoretically lose an increment.Assessment: Harmless in practice — shutdown happens one event later. Same-teammate concurrent idles can't occur.
Fix: Hold fcntl lock across entire read-modify-write cycle.
Revisit when: Concurrent idle count corruption observed.
Reference
docs/plans/2026-02-19-sdk-optimization-design.md