capt-hook 12.83.0__tar.gz → 12.83.2__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (245) hide show
  1. {capt_hook-12.83.0 → capt_hook-12.83.2}/PKG-INFO +1 -1
  2. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/.claude-plugin/plugin.json +1 -1
  3. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/builtin_packs/general/hooks/_sessions.py +35 -18
  4. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/dispatch.py +249 -50
  5. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/hook_lint.py +87 -2
  6. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/primitives/llm.py +17 -8
  7. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/review/cli.py +3 -2
  8. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/review/pipeline.py +82 -13
  9. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/review/scan.py +84 -41
  10. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/review/settings.py +14 -1
  11. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/snapshots/review.py +20 -18
  12. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/util/reqenv.py +108 -3
  13. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/worker/__main__.py +1 -1
  14. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/worker/runtime.py +57 -13
  15. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/worker/service.py +9 -1
  16. {capt_hook-12.83.0 → capt_hook-12.83.2}/pyproject.toml +1 -1
  17. {capt_hook-12.83.0 → capt_hook-12.83.2}/.gitignore +0 -0
  18. {capt_hook-12.83.0 → capt_hook-12.83.2}/LICENSE +0 -0
  19. {capt_hook-12.83.0 → capt_hook-12.83.2}/README.md +0 -0
  20. {capt_hook-12.83.0 → capt_hook-12.83.2}/capt_hook_client/__init__.py +0 -0
  21. {capt_hook-12.83.0 → capt_hook-12.83.2}/capt_hook_client/__main__.py +0 -0
  22. {capt_hook-12.83.0 → capt_hook-12.83.2}/capt_hook_client/client.py +0 -0
  23. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/.mcp.json +0 -0
  24. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/__init__.py +0 -0
  25. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/__init__.pyi +0 -0
  26. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/__main__.py +0 -0
  27. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/annotations.py +0 -0
  28. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/app.py +0 -0
  29. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/ast_grep.py +0 -0
  30. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/bindings.py +0 -0
  31. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/builtin_packs/__init__.py +0 -0
  32. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/builtin_packs/fixes/__init__.py +0 -0
  33. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/builtin_packs/fixes/hooks/__init__.py +0 -0
  34. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/builtin_packs/fixes/hooks/_lib.py +0 -0
  35. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/builtin_packs/fixes/hooks/scratch_writes.py +0 -0
  36. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/builtin_packs/fixes/hooks/teammate_permissions.py +0 -0
  37. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/builtin_packs/general/__init__.py +0 -0
  38. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/builtin_packs/general/hooks/__init__.py +0 -0
  39. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/builtin_packs/general/hooks/_lib.py +0 -0
  40. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/builtin_packs/general/hooks/commands.py +0 -0
  41. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/builtin_packs/general/hooks/comments.py +0 -0
  42. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/builtin_packs/general/hooks/deletions.py +0 -0
  43. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/builtin_packs/general/hooks/detours.py +0 -0
  44. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/builtin_packs/general/hooks/docs.py +0 -0
  45. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/builtin_packs/general/hooks/grants.py +0 -0
  46. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/builtin_packs/general/hooks/hook_files.py +0 -0
  47. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/builtin_packs/general/hooks/models.py +0 -0
  48. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/builtin_packs/general/hooks/plain_english.py +0 -0
  49. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/builtin_packs/general/hooks/plans.py +0 -0
  50. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/builtin_packs/general/hooks/prompts/fragments/deliverable_rubric.md +0 -0
  51. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/builtin_packs/general/hooks/prompts/fragments/workflow_script_header.md +0 -0
  52. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/builtin_packs/general/hooks/prompts/models/browser_delegation_nudge.md +0 -0
  53. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/builtin_packs/general/hooks/prompts/models/implementation_spawn_nudge.md +0 -0
  54. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/builtin_packs/general/hooks/prompts/models/inline_edit_nudge.md +0 -0
  55. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/builtin_packs/general/hooks/prompts/models/prose_spawn_gate.md +0 -0
  56. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/builtin_packs/general/hooks/prompts/models/prose_workflow_nudge.md +0 -0
  57. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/builtin_packs/general/hooks/prompts/models/review_routing_spawn_nudge.md +0 -0
  58. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/builtin_packs/general/hooks/prompts/models/review_routing_workflow_nudge.md +0 -0
  59. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/builtin_packs/general/hooks/prompts/models/writing_docs_spawn_nudge.md +0 -0
  60. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/builtin_packs/general/hooks/prompts/models/writing_docs_workflow_nudge.md +0 -0
  61. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/builtin_packs/general/hooks/prompts/plain_english_rules.md +0 -0
  62. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/builtin_packs/general/hooks/prompts/tools/preload_nudge.md +0 -0
  63. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/builtin_packs/general/hooks/prompts.py +0 -0
  64. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/builtin_packs/general/hooks/questions.py +0 -0
  65. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/builtin_packs/general/hooks/review.py +0 -0
  66. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/builtin_packs/general/hooks/sessions.py +0 -0
  67. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/builtin_packs/general/hooks/stops.py +0 -0
  68. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/builtin_packs/general/hooks/tasks.py +0 -0
  69. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/builtin_packs/general/hooks/tombstones.py +0 -0
  70. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/builtin_packs/general/hooks/tooling.py +0 -0
  71. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/builtin_packs/general/hooks/tools.py +0 -0
  72. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/builtin_packs/general/pack.toml +0 -0
  73. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/builtin_packs/go/__init__.py +0 -0
  74. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/builtin_packs/go/hooks/__init__.py +0 -0
  75. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/builtin_packs/go/hooks/testing.py +0 -0
  76. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/builtin_packs/go/hooks/toolchain.py +0 -0
  77. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/builtin_packs/graphite/__init__.py +0 -0
  78. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/builtin_packs/graphite/gitdir/.graphite_repo_config +0 -0
  79. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/builtin_packs/graphite/hooks/__init__.py +0 -0
  80. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/builtin_packs/graphite/hooks/_lib.py +0 -0
  81. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/builtin_packs/graphite/hooks/queue.py +0 -0
  82. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/builtin_packs/graphite/hooks/vcs.py +0 -0
  83. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/builtin_packs/performance/__init__.py +0 -0
  84. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/builtin_packs/performance/hooks/__init__.py +0 -0
  85. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/builtin_packs/performance/hooks/filesystem.py +0 -0
  86. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/builtin_packs/performance/hooks/pipelining.py +0 -0
  87. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/builtin_packs/python/__init__.py +0 -0
  88. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/builtin_packs/python/hooks/__init__.py +0 -0
  89. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/builtin_packs/python/hooks/style.py +0 -0
  90. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/builtin_packs/python/hooks/testing.py +0 -0
  91. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/builtin_packs/python/hooks/toolchain.py +0 -0
  92. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/builtin_packs/steering/__init__.py +0 -0
  93. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/builtin_packs/steering/hooks/__init__.py +0 -0
  94. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/builtin_packs/steering/hooks/steering.py +0 -0
  95. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/builtin_packs/steering/hooks/teammates.py +0 -0
  96. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/builtin_packs/steering/hooks/workarounds.py +0 -0
  97. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/builtin_packs/steering/pack.toml +0 -0
  98. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/classifiers/__init__.py +0 -0
  99. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/classifiers/conductor.py +0 -0
  100. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/classifiers/droid.py +0 -0
  101. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/classifiers/lane.py +0 -0
  102. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/classifiers/native.py +0 -0
  103. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/cli.py +0 -0
  104. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/cmd.py +0 -0
  105. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/command_schema.py +0 -0
  106. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/command_schemas.py +0 -0
  107. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/conditions.py +0 -0
  108. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/confirm.py +0 -0
  109. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/context.py +0 -0
  110. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/contexts.py +0 -0
  111. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/daemon/__init__.py +0 -0
  112. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/daemon/context.py +0 -0
  113. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/daemon/decision_writer.py +0 -0
  114. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/daemon/logsink.py +0 -0
  115. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/daemon/registry.py +0 -0
  116. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/daemon/tree.py +0 -0
  117. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/decisions.py +0 -0
  118. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/desktop/__init__.py +0 -0
  119. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/desktop/cli.py +0 -0
  120. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/desktop/client.py +0 -0
  121. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/doc_conventions.py +0 -0
  122. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/durable.py +0 -0
  123. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/events.py +0 -0
  124. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/faults.py +0 -0
  125. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/fields.py +0 -0
  126. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/file.py +0 -0
  127. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/grants/__init__.py +0 -0
  128. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/grants/cli.py +0 -0
  129. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/grants/declare.py +0 -0
  130. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/grants/evidence.py +0 -0
  131. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/grants/judge.py +0 -0
  132. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/grants/orca.py +0 -0
  133. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/grants/records.py +0 -0
  134. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/grants/rules.py +0 -0
  135. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/grants/store.py +0 -0
  136. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/guard_literal.py +0 -0
  137. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/guard_literal.sh +0 -0
  138. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/heartbeat.py +0 -0
  139. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/hooks/hooks.json +0 -0
  140. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/loader.py +0 -0
  141. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/log.py +0 -0
  142. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/mcp_server.py +0 -0
  143. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/packs/__init__.py +0 -0
  144. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/packs/manager.py +0 -0
  145. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/packs/plugins.py +0 -0
  146. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/pause.py +0 -0
  147. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/primitives/__init__.py +0 -0
  148. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/primitives/commands.py +0 -0
  149. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/primitives/lint.py +0 -0
  150. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/primitives/nudge.py +0 -0
  151. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/primitives/permissions.py +0 -0
  152. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/primitives/provision.py +0 -0
  153. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/primitives/rewrite.py +0 -0
  154. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/primitives/workflow.py +0 -0
  155. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/prompt.py +0 -0
  156. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/py.typed +0 -0
  157. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/review/__init__.py +0 -0
  158. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/review/announce.py +0 -0
  159. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/review/dashboard.py +0 -0
  160. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/review/fix.py +0 -0
  161. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/review/formats.py +0 -0
  162. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/review/judge.py +0 -0
  163. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/review/notify.py +0 -0
  164. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/review/prompts.py +0 -0
  165. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/review/repo.py +0 -0
  166. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/review/routing.py +0 -0
  167. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/review/snapshot.py +0 -0
  168. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/review/status.py +0 -0
  169. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/review/store.py +0 -0
  170. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/review/sync.py +0 -0
  171. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/review/triage.py +0 -0
  172. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/scripts/install-binary.sh +0 -0
  173. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/scripts/install-mcp.sh +0 -0
  174. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/session.py +0 -0
  175. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/settings.py +0 -0
  176. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/signals/__init__.py +0 -0
  177. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/signals/nlp.py +0 -0
  178. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/skills/authoring-hooks/SKILL.md +0 -0
  179. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/skills/authoring-hooks/references/capt-hook-api.md +0 -0
  180. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/skills/authoring-hooks/references/pattern-catalog.md +0 -0
  181. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/skills/authoring-hooks/references/pitfalls.md +0 -0
  182. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/skills/authoring-hooks/references/testing-hooks.md +0 -0
  183. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/skills/bootstrapping-hooks/SKILL.md +0 -0
  184. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/skills/scanning-sessions/SKILL.md +0 -0
  185. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/skills/scanning-sessions/references/pr-workflow.md +0 -0
  186. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/skills/scanning-sessions/references/review-cli.md +0 -0
  187. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/skills/translating-styleguides/SKILL.md +0 -0
  188. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/skills/translating-styleguides/references/llm-rule-patterns.md +0 -0
  189. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/skills/translating-styleguides/references/matcher-reference.md +0 -0
  190. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/skills/translating-styleguides/references/tier-rubric.md +0 -0
  191. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/snapshots/__init__.py +0 -0
  192. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/snapshots/client.py +0 -0
  193. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/snapshots/contracts.py +0 -0
  194. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/snapshots/schema.py +0 -0
  195. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/snapshots/schemas/config.schema.json +0 -0
  196. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/snapshots/schemas/context.schema.json +0 -0
  197. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/snapshots/schemas/host-request.schema.json +0 -0
  198. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/snapshots/schemas/host-response.schema.json +0 -0
  199. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/snapshots/schemas/request.schema.json +0 -0
  200. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/snapshots/schemas/response.schema.json +0 -0
  201. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/snapshots/schemas/tool_registry.schema.json +0 -0
  202. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/snapshots/validation.py +0 -0
  203. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/snapshots/worker.py +0 -0
  204. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/state.py +0 -0
  205. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/style/__init__.py +0 -0
  206. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/style/ast_grep.py +0 -0
  207. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/style/matchers.py +0 -0
  208. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/style/scope.py +0 -0
  209. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/style/types.py +0 -0
  210. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/tasks.py +0 -0
  211. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/templates/example_hook.py.tmpl +0 -0
  212. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/testing/__init__.py +0 -0
  213. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/testing/fixtures.py +0 -0
  214. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/testing/helpers.py +0 -0
  215. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/testing/session_cache.py +0 -0
  216. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/testing/snapshots.py +0 -0
  217. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/testing/types.py +0 -0
  218. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/transcripts.py +0 -0
  219. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/turn.py +0 -0
  220. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/types.py +0 -0
  221. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/update/__init__.py +0 -0
  222. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/update/cli.py +0 -0
  223. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/update/launchers.py +0 -0
  224. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/update/settings.py +0 -0
  225. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/update/updater.py +0 -0
  226. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/util/__init__.py +0 -0
  227. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/util/automode.py +0 -0
  228. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/util/caching.py +0 -0
  229. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/util/fs.py +0 -0
  230. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/util/globbing.py +0 -0
  231. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/util/http.py +0 -0
  232. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/util/model_cache.py +0 -0
  233. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/util/paths.py +0 -0
  234. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/util/payload.py +0 -0
  235. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/util/proc.py +0 -0
  236. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/util/scratch.py +0 -0
  237. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/util/shell.py +0 -0
  238. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/util/text.py +0 -0
  239. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/util/userpath.py +0 -0
  240. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/util/vcs.py +0 -0
  241. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/worker/__init__.py +0 -0
  242. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/worker/fail_open.py +0 -0
  243. {capt_hook-12.83.0 → capt_hook-12.83.2}/captain_hook/worker/protocol.py +0 -0
  244. {capt_hook-12.83.0 → capt_hook-12.83.2}/hatch_build.py +0 -0
  245. {capt_hook-12.83.0 → capt_hook-12.83.2}/internal/wireproto/guard.json +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: capt-hook
3
- Version: 12.83.0
3
+ Version: 12.83.2
4
4
  Summary: Stop repeating yourself to Claude.
5
5
  Project-URL: Homepage, https://github.com/yasyf/captain-hook
6
6
  Project-URL: Documentation, https://yasyf.github.io/captain-hook/
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "captain-hook",
3
- "version": "12.82.0",
3
+ "version": "12.83.1",
4
4
  "displayName": "Captain Hook",
5
5
  "description": "Skills for the capt-hook declarative hook framework: bootstrap gates and nudges from a repo's conventions, and translate style guides into enforced StyleRules.",
6
6
  "author": {
@@ -7,13 +7,14 @@ import re
7
7
  import shlex
8
8
  import subprocess
9
9
  import threading
10
+ from collections import OrderedDict
10
11
  from dataclasses import dataclass, field
11
12
  from datetime import UTC, datetime, timedelta
12
- from functools import cached_property, partial, reduce
13
+ from functools import partial, reduce
13
14
  from itertools import product
14
15
  from math import prod
15
16
  from pathlib import Path, PurePath
16
- from typing import TYPE_CHECKING, Any
17
+ from typing import TYPE_CHECKING, Any, ClassVar
17
18
 
18
19
  from cc_transcript.tools import BashCall
19
20
  from loguru import logger
@@ -22,7 +23,6 @@ from captain_hook import Event, Input, LambdaCondition, on
22
23
  from captain_hook.bindings import Resolution, Resolved, Unknown, Unresolved, program_name, references
23
24
  from captain_hook.cmd import Cmd
24
25
  from captain_hook.command_schemas import ORCA, OSASCRIPT
25
- from captain_hook.dispatch import SYNC_DEADLINE_MARGIN_SECONDS, collect_budget
26
26
  from captain_hook.grants import Allowed, Evidence, Grants, Judge, Proposal, Rulings, StandingRulings
27
27
  from captain_hook.guard_literal import FOLD_TABLE, GUARDED_WORD, QUOTING_CHARS, names_guarded
28
28
  from captain_hook.util import proc, reqenv
@@ -127,7 +127,7 @@ SPELLING_LIMIT = 60
127
127
  SESSION_ENV = re.compile(r"(?<!\S)CLAUDE_CODE_SESSION_ID=(\S*)")
128
128
  PROBE_TIMEOUT = 2.0
129
129
  PROBE_FALLBACK_DIRS = ("/opt/homebrew/bin", "/usr/local/bin", os.path.expanduser("~/.local/bin"))
130
- LAST_SCAN = threading.local()
130
+ SCAN_CACHE_LIMIT = 16
131
131
  IDLE_WAIT_MS = 1000
132
132
  SCREEN_LINES = 40
133
133
  PROMPT_WINDOW = 8
@@ -395,8 +395,7 @@ class Ownership:
395
395
 
396
396
 
397
397
  def probe_timeout(reason: str, ceiling: float = PROBE_TIMEOUT) -> float | Unreadable:
398
- budget = collect_budget(SYNC_DEADLINE_MARGIN_SECONDS)
399
- if budget is None:
398
+ if (budget := reqenv.seconds_left()) is None:
400
399
  return ceiling
401
400
  if budget < 0.5:
402
401
  return Unreadable(f"the caller deadline is too close to {reason}")
@@ -448,6 +447,8 @@ def terminal_pid(handle: str) -> int | Unreadable:
448
447
  class Facts:
449
448
  def __init__(self, session: str | None = None) -> None:
450
449
  self.session = session
450
+ self._guard = threading.Lock()
451
+ self._ownership: Ownership | Unreadable | None = None
451
452
 
452
453
  def started_here(self, row: ProcessRow) -> bool:
453
454
  if self.session is None or isinstance(timeout := probe_timeout("read a process environment"), Unreadable):
@@ -455,12 +456,12 @@ class Facts:
455
456
  shown = proc.environment(row, timeout=timeout)
456
457
  return shown is not None and set(SESSION_ENV.findall(shown)) == {self.session}
457
458
 
458
- @cached_property
459
+ @property
459
460
  def ownership(self) -> Ownership | Unreadable:
460
- if isinstance(timeout := probe_timeout("read the process table"), Unreadable):
461
- return timeout
462
- table = proc.process_table(timeout=timeout)
463
- return Unreadable("the process table could not be read") if table is None else Ownership.resolve(table)
461
+ with self._guard:
462
+ if self._ownership is None:
463
+ self._ownership = read_ownership()
464
+ return self._ownership
464
465
 
465
466
  def terminal_tree(self, handle: str) -> tuple[ProcessRow, ...] | Unreadable:
466
467
  if isinstance(ownership := self.ownership, Unreadable):
@@ -472,6 +473,13 @@ class Facts:
472
473
  return (root, *ownership.table.descendants(pid))
473
474
 
474
475
 
476
+ def read_ownership() -> Ownership | Unreadable:
477
+ if isinstance(timeout := probe_timeout("read the process table"), Unreadable):
478
+ return timeout
479
+ table = proc.process_table(timeout=timeout)
480
+ return Unreadable("the process table could not be read") if table is None else Ownership.resolve(table)
481
+
482
+
475
483
  def unresolvable(spelling: str, reason: str, fix: str) -> str:
476
484
  return f"BLOCKED: `{spelling}` cannot be verified: {reason}. {fix}"
477
485
 
@@ -743,21 +751,30 @@ class Unparsed:
743
751
 
744
752
  @dataclass(slots=True)
745
753
  class Scan:
754
+ LOCK: ClassVar[threading.Lock] = threading.Lock()
755
+ CACHE: ClassVar[OrderedDict[int, Scan]] = OrderedDict()
746
756
  raw: object
747
757
  facts: Facts = field(default_factory=Facts)
748
758
  calls: list[Call] = field(default_factory=list)
749
759
  respelled: list[Call] = field(default_factory=list)
750
760
  unparsed: list[Unparsed] = field(default_factory=list)
761
+ guard: threading.Lock = field(default_factory=threading.Lock)
762
+ scanned: bool = False
751
763
 
752
764
  @classmethod
753
765
  def of(cls, evt: BaseHookEvent) -> Scan:
754
- last: Scan | None = getattr(LAST_SCAN, "scan", None)
755
- if last is not None and last.raw is evt._raw:
756
- return last
757
- scan = cls(evt._raw, Facts(evt._raw.get("session_id")))
758
- for text in filter(names_guarded, candidate_texts(evt)):
759
- scan.read(text.encode(errors="replace").decode(), f"this `{evt.tool_name}` payload", evt.cwd)
760
- LAST_SCAN.scan = scan
766
+ with cls.LOCK:
767
+ scan = cls.CACHE.get(id(evt._raw))
768
+ if scan is None or scan.raw is not evt._raw:
769
+ scan = cls.CACHE[id(evt._raw)] = cls(evt._raw, Facts(evt._raw.get("session_id")))
770
+ cls.CACHE.move_to_end(id(evt._raw))
771
+ while len(cls.CACHE) > SCAN_CACHE_LIMIT:
772
+ cls.CACHE.popitem(last=False)
773
+ with scan.guard:
774
+ if not scan.scanned:
775
+ for text in filter(names_guarded, candidate_texts(evt)):
776
+ scan.read(text.encode(errors="replace").decode(), f"this `{evt.tool_name}` payload", evt.cwd)
777
+ scan.scanned = True
761
778
  return scan
762
779
 
763
780
  def read(
@@ -5,10 +5,11 @@ from __future__ import annotations
5
5
  import json
6
6
  import threading
7
7
  from concurrent.futures import Future, ThreadPoolExecutor, wait
8
- from contextlib import contextmanager
8
+ from contextlib import AbstractContextManager, contextmanager, nullcontext
9
9
  from contextvars import ContextVar, copy_context
10
10
  from copy import copy
11
- from dataclasses import replace
11
+ from dataclasses import dataclass, replace
12
+ from functools import partial
12
13
  from pathlib import Path
13
14
  from typing import TYPE_CHECKING, Any
14
15
 
@@ -27,22 +28,29 @@ from captain_hook.util import reqenv
27
28
  from captain_hook.util.caching import once
28
29
 
29
30
  if TYPE_CHECKING:
30
- from collections.abc import Iterator, Sequence
31
+ from collections.abc import Callable, Iterator, Sequence
31
32
 
32
33
  from captain_hook.events import BaseHookEvent
33
34
 
34
35
  ADVISORY_SEPARATOR = "Additional advisories (not the reason for the deny):"
35
36
  SYNC_DEADLINE_MARGIN_SECONDS = 5.0
37
+ MANDATORY_HOOK_THREADS = 8
38
+ MANDATORY_COLLECT_SLACK_SECONDS = 0.25
36
39
  ASYNC_HOOK_TIMEOUT_SECONDS = 180.0
37
40
  HOOK_FANOUT_THREADS = 64
38
41
  BACKGROUND_FANOUT_THREADS = 8
39
42
  OFFLOAD_THREADS = 4
40
43
 
41
44
  type Envelope = dict[str, Any] | str
45
+ type Settle = Callable[[HookResult | None], None]
42
46
 
43
47
  _SURFACE_HANDLER_ERRORS: ContextVar[bool] = ContextVar("captain_hook_surface_handler_errors", default=False)
44
48
 
45
49
 
50
+ class MandatoryDeadlinePassed(Exception):
51
+ """A mandatory hook missed its verdict inside the caller's deadline: queued past it, or still running at it."""
52
+
53
+
46
54
  @once
47
55
  def fanout_budget() -> threading.BoundedSemaphore:
48
56
  """The worker-wide bound on synchronous hook groups in flight: :data:`HOOK_FANOUT_THREADS` permits.
@@ -65,7 +73,7 @@ class Fanout:
65
73
  """
66
74
 
67
75
  def __init__(self, groups: int) -> None:
68
- self.abandoned = threading.Event()
76
+ self.abandoned = reqenv.Cutoff()
69
77
  self.pool = ThreadPoolExecutor(max_workers=groups, thread_name_prefix="capt-hook-hook")
70
78
  self._budget = fanout_budget()
71
79
  self._held = 0
@@ -86,7 +94,7 @@ class Fanout:
86
94
  self._budget.release()
87
95
 
88
96
  def close(self) -> None:
89
- self.abandoned.set()
97
+ self.abandoned.close()
90
98
  with self._guard:
91
99
  held, self._held = self._held, 0
92
100
  for _ in range(held):
@@ -104,6 +112,17 @@ def background_pool() -> ThreadPoolExecutor:
104
112
  return ThreadPoolExecutor(max_workers=BACKGROUND_FANOUT_THREADS, thread_name_prefix="capt-hook-async-hook")
105
113
 
106
114
 
115
+ @once
116
+ def mandatory_pool() -> ThreadPoolExecutor:
117
+ """The one process-wide pool every event's ``mandatory=True`` hooks run on, :data:`MANDATORY_HOOK_THREADS` wide.
118
+
119
+ Fixed rather than sized per event, so the thread count never scales with the events in flight;
120
+ a hook still queued or still running when its caller's deadline passes is the event's
121
+ :class:`MandatoryDeadlinePassed` instead of a late completion.
122
+ """
123
+ return ThreadPoolExecutor(max_workers=MANDATORY_HOOK_THREADS, thread_name_prefix="capt-hook-mandatory")
124
+
125
+
107
126
  @once
108
127
  def offload_pool() -> ThreadPoolExecutor:
109
128
  return ThreadPoolExecutor(max_workers=OFFLOAD_THREADS, thread_name_prefix="capt-hook-offload")
@@ -176,11 +195,13 @@ def execute_hook(
176
195
  entry: RegisteredHook,
177
196
  evt: BaseHookEvent,
178
197
  session_dir: Path | None = None,
198
+ *,
199
+ settle: Settle | None = None,
179
200
  ) -> HookResult | None:
180
201
  from captain_hook.transcripts import release_transcript
181
202
 
182
203
  try:
183
- return _execute_hook(entry, evt, session_dir)
204
+ return _execute_hook(entry, evt, session_dir, settle)
184
205
  finally:
185
206
  release_transcript(evt.ctx.transcript)
186
207
 
@@ -188,7 +209,8 @@ def execute_hook(
188
209
  def _execute_hook(
189
210
  entry: RegisteredHook,
190
211
  evt: BaseHookEvent,
191
- session_dir: Path | None = None,
212
+ session_dir: Path | None,
213
+ settle: Settle | None,
192
214
  ) -> HookResult | None:
193
215
  """Execute a single registered hook under a reserve-then-release ``max_fires`` protocol.
194
216
 
@@ -198,7 +220,13 @@ def _execute_hook(
198
220
  handler runs (reserve); anything but a delivered truthy result gives the slot back under a
199
221
  second lock (release) — a falsy result, an ``Exception``, or an abnormal ``BaseException``
200
222
  (``SystemExit``/``KeyboardInterrupt``), which releases and then re-propagates so the abort is
201
- not silently swallowed. Uncapped hooks (``max_fires is None``) skip the lock entirely.
223
+ not silently swallowed. A truthy result reached once nobody waits on it any more (the caller's
224
+ deadline passed, or dispatch gave up on the event) is not delivered either: :func:`deliver`
225
+ publishes the caller's *settle* under :func:`captain_hook.util.reqenv.publish`, which unwinds
226
+ as :class:`captain_hook.util.reqenv.Abandoned` instead once the event closed, and writes the
227
+ ledger row only once that publication was accepted, so the slot and the row come back or
228
+ stay together and a closure never splits an accepted verdict from its record. Uncapped
229
+ hooks (``max_fires is None``) skip the lock entirely.
202
230
  """
203
231
  hook_session_dir = (session_dir / entry.state_key / (evt.agent_id or "main")) if session_dir else None
204
232
  if hook_session_dir:
@@ -206,28 +234,36 @@ def _execute_hook(
206
234
  store = SessionStore(hook_session_dir)
207
235
 
208
236
  if entry.spec.max_fires is None:
209
- if result := run_handler(entry, evt):
210
- record_fire(entry, evt, result)
211
- return result
237
+ return deliver(entry, evt, run_handler(entry, evt), settle)
212
238
 
213
239
  with store[HookState].mutate() as hook_state:
214
240
  if hook_state.fire_count >= entry.spec.max_fires:
215
- return None
241
+ return deliver(entry, evt, None, settle)
216
242
  hook_state.fire_count += 1
217
243
 
218
- delivered = False
244
+ delivered: HookResult | None = None
219
245
  try:
220
- if result := run_handler(entry, evt):
221
- delivered = True
222
- record_fire(entry, evt, result)
223
- return result
224
- return None
246
+ delivered = deliver(entry, evt, run_handler(entry, evt), settle)
247
+ return delivered
225
248
  finally:
226
- if not delivered:
249
+ if delivered is None:
227
250
  with store[HookState].mutate() as hook_state:
228
251
  hook_state.fire_count -= 1
229
252
 
230
253
 
254
+ def deliver(
255
+ entry: RegisteredHook, evt: BaseHookEvent, result: HookResult | None, settle: Settle | None
256
+ ) -> HookResult | None:
257
+ def accept() -> None:
258
+ if settle is not None:
259
+ settle(result)
260
+
261
+ reqenv.publish(accept)
262
+ if result:
263
+ record_fire(entry, evt, result)
264
+ return result
265
+
266
+
231
267
  class FirstBlock:
232
268
  """The registration index of the earliest hook to block, shared across one event's fan-out.
233
269
 
@@ -618,51 +654,214 @@ def prepare_hook_events(
618
654
  return [entries[index] for index in kept], [forks[index] for index in kept]
619
655
 
620
656
 
657
+ def completion_key(entry: RegisteredHook, ordinal: int) -> str:
658
+ return f"{entry.state_key}#{ordinal}"
659
+
660
+
661
+ def mandatory_completions(event: Event) -> dict[str, RegisteredHook]:
662
+ """The completion each of *event*'s ``mandatory=True`` registrations records, keyed per registration.
663
+
664
+ Two registrations sharing a state key share one session directory but each owes the event its
665
+ own verdict, so the key carries the registration's place among the event's mandatory hooks and
666
+ the worker can hold every registration to exactly one completion.
667
+ """
668
+ return {completion_key(hook, ordinal): hook for ordinal, hook in enumerate(get_mandatory_hooks(event))}
669
+
670
+
671
+ @dataclass(frozen=True, slots=True)
672
+ class MandatoryBound:
673
+ """The absolute deadlines one event's mandatory hooks run under, fixed once when the event starts.
674
+
675
+ ``deadline_unix_ms`` is the hooks' own: the caller's deadline less the reply margin when that
676
+ fits, the caller's own once the request is already inside the margin, ``None`` for the cold
677
+ CLI. ``cutoff`` is where :func:`collect_mandatory` stops waiting,
678
+ :data:`MANDATORY_COLLECT_SLACK_SECONDS` past the hooks' deadline and never past the caller's;
679
+ bound as the hooks' abandon signal, a verdict reached after it unwinds at its
680
+ :func:`captain_hook.util.reqenv.checkpoint` instead of recording a completion or keeping a
681
+ fire slot. Both are absolute, so a pause between reading the clock and binding never moves
682
+ either later.
683
+ """
684
+
685
+ deadline_unix_ms: int | None
686
+ cutoff: reqenv.Cutoff
687
+
688
+ @classmethod
689
+ def of(cls, margin: float) -> MandatoryBound:
690
+ if (ov := reqenv.current()) is None or ov.deadline_unix_ms == 0:
691
+ return cls(None, reqenv.Cutoff())
692
+ deadline = ov.deadline_unix_ms if reqenv.deadline_within(margin) else ov.deadline_unix_ms - int(margin * 1000)
693
+ slack = int(MANDATORY_COLLECT_SLACK_SECONDS * 1000)
694
+ return cls(deadline, reqenv.Cutoff(min(ov.deadline_unix_ms, deadline + slack)))
695
+
696
+ def deadline(self) -> AbstractContextManager[None]:
697
+ return nullcontext() if self.deadline_unix_ms is None else reqenv.deadline_at(self.deadline_unix_ms)
698
+
699
+
700
+ def run_mandatory(
701
+ entry: RegisteredHook,
702
+ evt: BaseHookEvent,
703
+ session_dir: Path | None,
704
+ ordinal: int,
705
+ bound: MandatoryBound,
706
+ future: Future[HookResult | None],
707
+ ) -> None:
708
+ """Run one mandatory hook under the event's :class:`MandatoryBound`, then publish its completion into *future*.
709
+
710
+ The completion and the settlement are one :func:`captain_hook.util.reqenv.publish` under the
711
+ cutoff's closure lock, and nothing that blocks runs under it: a verdict is accepted whole
712
+ before the collector closes the event or refused whole after it, never half-recorded, and
713
+ its ledger row follows the acceptance on this thread. Incomplete
714
+ transcript evidence leaves the hook unrun, settling the future with no completion; a cutoff
715
+ already passed when the hook starts or closed by the time it publishes, or any other
716
+ exception, is the whole event's and propagates through the future. A publication refused
717
+ after it settled, because it finished past the cutoff or still held the closure when the
718
+ collector stopped waiting, has already settled its future into a phase the collector fails,
719
+ so that refusal only withholds the row and the slot.
720
+ """
721
+ if bound.cutoff.is_set():
722
+ raise MandatoryDeadlinePassed(f"{entry.name}: the caller's deadline passed while the hook was queued")
723
+ key = completion_key(entry, ordinal)
724
+
725
+ def settle(result: HookResult | None) -> None:
726
+ reqenv.note_mandatory_completed(key)
727
+ future.set_result(result)
728
+
729
+ try:
730
+ try:
731
+ with bound.deadline(), surfacing_handler_errors(), foreground_evidence(MANDATORY_WORK_SECONDS):
732
+ if skips_event(entry.spec, evt) or not matches_conditions(entry.spec, evt):
733
+ reqenv.publish(partial(settle, None))
734
+ else:
735
+ execute_hook(entry, evt, session_dir, settle=settle)
736
+ except EvidenceIncomplete as exc:
737
+ if not fails_open(exc):
738
+ raise
739
+ logger.bind(hook=entry.name, status=exc.status, reason=exc.reason).warning(
740
+ "mandatory hook left unrun: evidence incomplete"
741
+ )
742
+ reqenv.publish(partial(future.set_result, None))
743
+ except reqenv.Abandoned:
744
+ if future.done():
745
+ return
746
+ raise MandatoryDeadlinePassed(f"{entry.name}: finished past the caller's deadline") from None
747
+
748
+
749
+ def run_mandatory_group(
750
+ group: Sequence[int],
751
+ entries: Sequence[RegisteredHook],
752
+ futures: Sequence[Future[HookResult | None]],
753
+ events: Sequence[BaseHookEvent],
754
+ session_dir: Path | None,
755
+ bound: MandatoryBound,
756
+ ) -> None:
757
+ """Run one state-key group's mandatory hooks in registration order, settling each entry's own future.
758
+
759
+ Registrations sharing a state key share one ``max_fires`` counter, so they run one after another
760
+ the way :func:`run_group` runs them: side by side, the first could reserve the slot the second
761
+ then skips, and a deny the second would have rendered is lost. A raising hook settles its own
762
+ future and cancels the rest of its group.
763
+ """
764
+ with reqenv.abandonable(bound.cutoff):
765
+ for position, index in enumerate(group):
766
+ future = futures[index]
767
+ if not future.set_running_or_notify_cancel():
768
+ continue
769
+ try:
770
+ run_mandatory(entries[index], events[index], session_dir, index, bound, future)
771
+ except BaseException as exc:
772
+ future.set_exception(exc)
773
+ for later in group[position + 1 :]:
774
+ futures[later].cancel()
775
+ return
776
+
777
+
778
+ def collect_mandatory(
779
+ entries: Sequence[RegisteredHook], futures: Sequence[Future[HookResult | None]], cutoff: reqenv.Cutoff
780
+ ) -> None:
781
+ """Wait for every mandatory future until *cutoff*, close it, then conclude the phase from what settled.
782
+
783
+ The closure comes first and takes the cutoff's lock, so every publication that beat it is a
784
+ settled future and none can follow it; only then is each future read, and the phase recorded
785
+ in :func:`captain_hook.util.reqenv.mandatory_phase` as settled or failed, exactly once. The
786
+ closure waits for the lock no longer than the cutoff itself: a publisher still inside it at
787
+ the cutoff is not waited for, the flag refuses every publisher after it, and the phase fails
788
+ whatever that publisher goes on to settle while the publisher itself is refused on its way
789
+ out, keeping no row or slot, so the collector returns by the cutoff however a hook's thread
790
+ was scheduled. A publication that finished settling past the cutoff before a delayed
791
+ collector closed is refused and fails the phase the same way, so only a verdict settled by
792
+ the cutoff is ever counted. Past the cutoff every hook not yet started is cancelled and
793
+ every one still running is the event's failure: a hook that ignores its budget keeps its
794
+ thread until it returns, but a verdict nobody waited for records no completion and keeps no
795
+ fire slot. A hook that raised dooms the event the same way.
796
+ """
797
+ phase = reqenv.mandatory_phase()
798
+ wait(futures, timeout=cutoff.seconds_left())
799
+ closed = cutoff.close(timeout=cutoff.seconds_left())
800
+ for future in futures:
801
+ future.cancel()
802
+ try:
803
+ for entry, future in zip(entries, futures, strict=True):
804
+ if future.cancelled():
805
+ raise MandatoryDeadlinePassed(f"{entry.name}: left unrun at the caller's deadline")
806
+ if not future.done():
807
+ raise MandatoryDeadlinePassed(f"{entry.name}: still running at the caller's deadline")
808
+ future.result()
809
+ if not closed:
810
+ raise MandatoryDeadlinePassed("a verdict was still publishing at the caller's deadline")
811
+ except BaseException:
812
+ phase.conclude("failed")
813
+ raise
814
+ phase.conclude("settled")
815
+
816
+
621
817
  def dispatch_mandatory(
622
818
  evt: BaseHookEvent,
623
819
  session_dir: Path | None = None,
820
+ margin: float = SYNC_DEADLINE_MARGIN_SECONDS,
624
821
  ) -> tuple[list[RegisteredHook], list[Future[HookResult | None]]]:
625
- """Run the event's ``mandatory=True`` hooks to their verdicts on the request thread, ahead of every budget.
822
+ """Run the event's ``mandatory=True`` hooks to their verdicts, ahead of every budget, and wait for all of them.
626
823
 
627
824
  The Go client denies a guarded call whose mandatory hooks it cannot see complete, so these
628
- take no fan-out permit, never skip at the deadline margin, and are never abandoned: each runs
629
- here in registration order and records its completion in
630
- :func:`captain_hook.util.reqenv.mandatory_completed` whether its conditions matched, its own
631
- opt-outs (:func:`captain_hook.app.skips_event`) left the event alone, or it ran to a verdict.
825
+ take no fan-out permit and never skip at the deadline margin: each state-key group runs on
826
+ :func:`mandatory_pool`, so a slow one never holds the guard registered after it behind it, and
827
+ each hook records its completion in :func:`captain_hook.util.reqenv.mandatory_completed`
828
+ whether its conditions matched, its own opt-outs (:func:`captain_hook.app.skips_event`) left
829
+ the event alone, or it ran to a verdict. Each hook runs under the event's
830
+ :class:`MandatoryBound`, the caller's deadline less *margin*, so an inner call that honors the
831
+ deadline returns while the reply can still be delivered, and :func:`collect_mandatory` waits
832
+ no longer than that.
632
833
  Incomplete transcript evidence records nothing — a mandatory hook is evidence-free by
633
834
  contract, so a fail-open skip leaves it unrun — and any other exception, a handler's included,
634
835
  is the whole event's: a crashed mandatory hook must read as no completion, never as a verdict.
635
836
  The settled futures fold into :func:`combine` at the hooks' own registration positions.
837
+ The worker turns a failed phase into the event's deny only when it recognizes the failure
838
+ and its reply reaches the client; a transport that goes silent is the client's call, which
839
+ retries a timed-out guard once and then warns.
636
840
  """
637
841
  from captain_hook.transcripts import fork_transcript, release_transcript
638
842
 
639
843
  entries = get_mandatory_hooks(evt.event)
640
- futures: list[Future[HookResult | None]] = []
641
- for entry in entries:
642
- fork = copy(evt)
643
- fork.ctx = evt.ctx.fork(fork_transcript(evt.ctx.transcript, entry.spec.transcript_events))
644
- fork.__dict__.pop("cmd", None)
645
- try:
646
- with surfacing_handler_errors(), foreground_evidence(MANDATORY_WORK_SECONDS):
647
- result = (
648
- execute_hook(entry, fork, session_dir)
649
- if not skips_event(entry.spec, fork) and matches_conditions(entry.spec, fork)
650
- else None
651
- )
652
- except EvidenceIncomplete as exc:
653
- if not fails_open(exc):
654
- raise
655
- logger.bind(hook=entry.name, status=exc.status, reason=exc.reason).warning(
656
- "mandatory hook left unrun: evidence incomplete"
657
- )
658
- result = None
659
- else:
660
- reqenv.note_mandatory_completed(entry.state_key)
661
- finally:
844
+ if not entries:
845
+ return [], []
846
+ forks: list[BaseHookEvent] = []
847
+ try:
848
+ for entry in entries:
849
+ fork = copy(evt)
850
+ fork.ctx = evt.ctx.fork(fork_transcript(evt.ctx.transcript, entry.spec.transcript_events))
851
+ fork.__dict__.pop("cmd", None)
852
+ forks.append(fork)
853
+ except BaseException:
854
+ for fork in forks:
662
855
  release_transcript(fork.ctx.transcript)
663
- future: Future[HookResult | None] = Future()
664
- future.set_result(result)
665
- futures.append(future)
856
+ raise
857
+ futures: list[Future[HookResult | None]] = [Future() for _ in entries]
858
+ for future, fork in zip(futures, forks, strict=True):
859
+ future.add_done_callback(lambda _, transcript=fork.ctx.transcript: release_transcript(transcript))
860
+ bound = MandatoryBound.of(margin)
861
+ pool = mandatory_pool()
862
+ for group in hook_groups(entries):
863
+ pool.submit(copy_context().run, run_mandatory_group, group, entries, futures, forks, session_dir, bound)
864
+ collect_mandatory(entries, futures, bound.cutoff)
666
865
  return entries, futures
667
866
 
668
867
 
@@ -696,7 +895,7 @@ def dispatch(
696
895
  :func:`captain_hook.util.reqenv.checkpoint`, and whatever never started is cancelled.
697
896
 
698
897
  The event's ``mandatory=True`` hooks are the exception to every bound above: they run first,
699
- to their verdicts, on this thread (:func:`dispatch_mandatory`), but fold at their own
898
+ to their verdicts, on their own pool (:func:`dispatch_mandatory`), but fold at their own
700
899
  registration positions, so a mandatory block dooms exactly the handler-backed hooks registered
701
900
  after it and an advisory hook registered before it keeps its run, its ledger write, and its
702
901
  claim on the deny's reason. ``advisory=False`` stops after them, so a caller already inside the
@@ -1,5 +1,6 @@
1
- """Lint hook files against the authoring bar: a message states the rule, then the remediation, and
2
- the hook code uses the declarative surface instead of hand-rolled parsing."""
1
+ """Lint hook files against the authoring bar: a message states the rule, then the remediation, the
2
+ hook code uses the declarative surface instead of hand-rolled parsing, and a mandatory hook stays
3
+ evidence-free."""
3
4
 
4
5
  from __future__ import annotations
5
6
 
@@ -70,6 +71,13 @@ TEXT_PARSERS = REGEX_METHODS | frozenset(
70
71
  )
71
72
  CONTEXT_TOOLS = frozenset({"Agent", "Task", "Skill", "Read", "Grep", "Glob"})
72
73
  ALLOWED_COMMENT = re.compile(r"#!|#\s*(?:TODO|FIXME|WORKAROUND|noqa|type:|pyright:|ruff:|fmt:|pragma)")
74
+ LLM_CALLS = frozenset({"llm_evaluate", "llm", "call_llm", "llm_gate", "llm_nudge", "prompt_check"})
75
+ TRANSCRIPT_ATTRIBUTES = frozenset({"t", "transcript"})
76
+ MANDATORY_EVIDENCE = (
77
+ "a mandatory hook is evidence-free; move the LLM or transcript check into an advisory hook registered "
78
+ "without mandatory=True (the lint follows helpers in this file, registrars imported from a sibling module, "
79
+ "and import aliases; a helper imported from another package or reached by dynamic dispatch is not seen)"
80
+ )
73
81
 
74
82
 
75
83
  @dataclass(frozen=True, slots=True)
@@ -320,6 +328,82 @@ def code_findings(path: Path, tree: ast.Module) -> Iterator[Finding]:
320
328
  yield Finding(path, getattr(node, "lineno", 1), "code", violation)
321
329
 
322
330
 
331
+ def registers_mandatory(call: ast.Call, registrars: frozenset[str]) -> bool:
332
+ return callee(call) in registrars or any(
333
+ keyword.arg == "mandatory" and isinstance(keyword.value, ast.Constant) and keyword.value.value is True
334
+ for keyword in call.keywords
335
+ )
336
+
337
+
338
+ def import_aliases(tree: ast.Module) -> dict[str, str]:
339
+ return {
340
+ alias.asname: alias.name.rsplit(".", 1)[-1]
341
+ for node in tree.body
342
+ if isinstance(node, ast.Import | ast.ImportFrom)
343
+ for alias in node.names
344
+ if alias.asname
345
+ }
346
+
347
+
348
+ def local_registrars(tree: ast.Module) -> frozenset[str]:
349
+ return frozenset(
350
+ target.id
351
+ for node in tree.body
352
+ for target, value in bindings(node)
353
+ if isinstance(target, ast.Name) and isinstance(value, ast.Call) and registers_mandatory(value, frozenset())
354
+ )
355
+
356
+
357
+ def imported_registrars(path: Path, tree: ast.Module) -> frozenset[str]:
358
+ return frozenset(
359
+ alias.asname or alias.name
360
+ for node in tree.body
361
+ if isinstance(node, ast.ImportFrom) and node.module
362
+ if (sibling := path.parent / f"{node.module.rsplit('.', 1)[-1]}.py").is_file()
363
+ for exported in [local_registrars(ast.parse(sibling.read_text(), filename=str(sibling)))]
364
+ for alias in node.names
365
+ if alias.name in exported
366
+ )
367
+
368
+
369
+ def mandatory_handlers(
370
+ path: Path, tree: ast.Module, functions: dict[str, ast.FunctionDef]
371
+ ) -> Iterator[ast.FunctionDef]:
372
+ registrars = local_registrars(tree) | imported_registrars(path, tree)
373
+ for node in ast.walk(tree):
374
+ match node:
375
+ case ast.FunctionDef(decorator_list=decorators) if any(
376
+ isinstance(call, ast.Call) and registers_mandatory(call, registrars) for call in decorators
377
+ ):
378
+ yield node
379
+ case ast.Call(func=ast.Call() as registration, args=[ast.Name(id=name)]) if (
380
+ name in functions and registers_mandatory(registration, registrars)
381
+ ):
382
+ yield functions[name]
383
+
384
+
385
+ def evidence_reads(
386
+ function: ast.FunctionDef, functions: dict[str, ast.FunctionDef], aliases: dict[str, str], seen: set[str]
387
+ ) -> Iterator[tuple[ast.AST, str]]:
388
+ seen.add(function.name)
389
+ for node in ast.walk(function):
390
+ match node:
391
+ case ast.Call() if (name := aliases.get(called := callee(node) or "", called)) in LLM_CALLS:
392
+ yield node, f"calls {name}"
393
+ case ast.Attribute(attr=attr, value=ast.Attribute(attr="ctx")) if attr in TRANSCRIPT_ATTRIBUTES:
394
+ yield node, f"reads {ast.unparse(node)}"
395
+ case ast.Call() if (name := callee(node)) in functions and name not in seen:
396
+ yield from evidence_reads(functions[name], functions, aliases, seen)
397
+
398
+
399
+ def mandatory_findings(path: Path, tree: ast.Module) -> Iterator[Finding]:
400
+ functions = {node.name: node for node in ast.walk(tree) if isinstance(node, ast.FunctionDef)}
401
+ aliases = import_aliases(tree)
402
+ for handler in mandatory_handlers(path, tree, functions):
403
+ for node, read in evidence_reads(handler, functions, aliases, set()):
404
+ yield Finding(path, node.lineno, "code", f"mandatory hook {handler.name} {read}; {MANDATORY_EVIDENCE}")
405
+
406
+
323
407
  def comment_findings(path: Path, source: str) -> Iterator[Finding]:
324
408
  for token in tokenize.generate_tokens(io.StringIO(source).readline):
325
409
  if token.type == tokenize.COMMENT and not ALLOWED_COMMENT.match(token.string):
@@ -334,6 +418,7 @@ def lint_source(path: Path, source: str) -> list[Finding]:
334
418
  *copy_findings(path, tree),
335
419
  *code_findings(path, tree),
336
420
  *escape_findings(path, tree),
421
+ *mandatory_findings(path, tree),
337
422
  *comment_findings(path, source),
338
423
  ],
339
424
  key=lambda finding: (finding.line, finding.rule, finding.detail),