typeclaw 0.48.13 → 0.50.0

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 (572) hide show
  1. package/dist/types/agent/attention-escalation.d.ts +18 -0
  2. package/dist/types/agent/auth.d.ts +7 -0
  3. package/dist/types/agent/compaction.d.ts +8 -0
  4. package/dist/types/agent/git-nudge.d.ts +6 -0
  5. package/dist/types/agent/guard-types.d.ts +25 -0
  6. package/dist/types/agent/guards.d.ts +7 -0
  7. package/dist/types/agent/idle-compaction.d.ts +7 -0
  8. package/dist/types/agent/index.d.ts +163 -0
  9. package/dist/types/agent/live-subagents.d.ts +113 -0
  10. package/dist/types/agent/llm-replay-sanitizer.d.ts +11 -0
  11. package/dist/types/agent/loop-guard.d.ts +67 -0
  12. package/dist/types/agent/model-fallback.d.ts +29 -0
  13. package/dist/types/agent/model-overrides.d.ts +8 -0
  14. package/dist/types/agent/multimodal/index.d.ts +2 -0
  15. package/dist/types/agent/multimodal/look-at.d.ts +60 -0
  16. package/dist/types/agent/multimodal/looker.d.ts +61 -0
  17. package/dist/types/agent/multimodal/read-redirect.d.ts +6 -0
  18. package/dist/types/agent/network/response-body.d.ts +1 -0
  19. package/dist/types/agent/network/safe-http.d.ts +46 -0
  20. package/dist/types/agent/plugin-tools.d.ts +129 -0
  21. package/dist/types/agent/proactive-next-step-nudge.d.ts +2 -0
  22. package/dist/types/agent/prompt-cache-key.d.ts +3 -0
  23. package/dist/types/agent/provider-error.d.ts +23 -0
  24. package/dist/types/agent/reload-tool.d.ts +10 -0
  25. package/dist/types/agent/restart/index.d.ts +31 -0
  26. package/dist/types/agent/restart-handoff/index.d.ts +32 -0
  27. package/dist/types/agent/restart-handoff/paths.d.ts +1 -0
  28. package/dist/types/agent/retry-same-ref.d.ts +41 -0
  29. package/dist/types/agent/reviewer-activity.d.ts +3 -0
  30. package/dist/types/agent/reviewer-bash-policy.d.ts +8 -0
  31. package/dist/types/agent/self.d.ts +1 -0
  32. package/dist/types/agent/session-meta.d.ts +28 -0
  33. package/dist/types/agent/session-origin.d.ts +65 -0
  34. package/dist/types/agent/subagent-cache-keepalive.d.ts +38 -0
  35. package/dist/types/agent/subagent-completion-reminder.d.ts +29 -0
  36. package/dist/types/agent/subagent-drain.d.ts +25 -0
  37. package/dist/types/agent/subagent-session.d.ts +3 -0
  38. package/dist/types/agent/subagents.d.ts +153 -0
  39. package/dist/types/agent/system-prompt.d.ts +7 -0
  40. package/dist/types/agent/throttle-circuit.d.ts +25 -0
  41. package/dist/types/agent/todo/continuation-policy.d.ts +54 -0
  42. package/dist/types/agent/todo/continuation-state.d.ts +11 -0
  43. package/dist/types/agent/todo/continuation-wiring.d.ts +32 -0
  44. package/dist/types/agent/todo/continuation.d.ts +21 -0
  45. package/dist/types/agent/todo/scope.d.ts +6 -0
  46. package/dist/types/agent/todo/store.d.ts +16 -0
  47. package/dist/types/agent/tool-error-remediation.d.ts +1 -0
  48. package/dist/types/agent/tool-file-safety.d.ts +78 -0
  49. package/dist/types/agent/tool-not-found-nudge.d.ts +9 -0
  50. package/dist/types/agent/tool-result-budget.d.ts +15 -0
  51. package/dist/types/agent/tools/channel-disengage.d.ts +18 -0
  52. package/dist/types/agent/tools/channel-edit.d.ts +19 -0
  53. package/dist/types/agent/tools/channel-fetch-attachment.d.ts +36 -0
  54. package/dist/types/agent/tools/channel-handoff.d.ts +13 -0
  55. package/dist/types/agent/tools/channel-history-render.d.ts +3 -0
  56. package/dist/types/agent/tools/channel-history.d.ts +25 -0
  57. package/dist/types/agent/tools/channel-log.d.ts +5 -0
  58. package/dist/types/agent/tools/channel-react.d.ts +23 -0
  59. package/dist/types/agent/tools/channel-read.d.ts +27 -0
  60. package/dist/types/agent/tools/channel-reply.d.ts +47 -0
  61. package/dist/types/agent/tools/channel-send.d.ts +42 -0
  62. package/dist/types/agent/tools/channel-session-search.d.ts +10 -0
  63. package/dist/types/agent/tools/curl-impersonate.d.ts +37 -0
  64. package/dist/types/agent/tools/ddg.d.ts +18 -0
  65. package/dist/types/agent/tools/grant-role.d.ts +25 -0
  66. package/dist/types/agent/tools/keyed-semaphore.d.ts +10 -0
  67. package/dist/types/agent/tools/post-github-review.d.ts +38 -0
  68. package/dist/types/agent/tools/restart.d.ts +25 -0
  69. package/dist/types/agent/tools/runtime-notice.d.ts +3 -0
  70. package/dist/types/agent/tools/search-retry.d.ts +16 -0
  71. package/dist/types/agent/tools/skip-response.d.ts +17 -0
  72. package/dist/types/agent/tools/spawn-subagent.d.ts +77 -0
  73. package/dist/types/agent/tools/stream-snapshot.d.ts +23 -0
  74. package/dist/types/agent/tools/subagent-access.d.ts +20 -0
  75. package/dist/types/agent/tools/subagent-cancel.d.ts +23 -0
  76. package/dist/types/agent/tools/subagent-output.d.ts +50 -0
  77. package/dist/types/agent/tools/todo/index.d.ts +14 -0
  78. package/dist/types/agent/tools/webfetch/adaptive-html.d.ts +29 -0
  79. package/dist/types/agent/tools/webfetch/fetch.d.ts +26 -0
  80. package/dist/types/agent/tools/webfetch/html-lexical.d.ts +27 -0
  81. package/dist/types/agent/tools/webfetch/index.d.ts +1 -0
  82. package/dist/types/agent/tools/webfetch/inline-style-visibility.d.ts +3 -0
  83. package/dist/types/agent/tools/webfetch/strategies/grep.d.ts +11 -0
  84. package/dist/types/agent/tools/webfetch/strategies/jq.d.ts +4 -0
  85. package/dist/types/agent/tools/webfetch/strategies/raw.d.ts +1 -0
  86. package/dist/types/agent/tools/webfetch/strategies/readability.d.ts +16 -0
  87. package/dist/types/agent/tools/webfetch/strategies/selector.d.ts +4 -0
  88. package/dist/types/agent/tools/webfetch/strategies/snapshot.d.ts +1 -0
  89. package/dist/types/agent/tools/webfetch/tool.d.ts +15 -0
  90. package/dist/types/agent/tools/webfetch/types.d.ts +32 -0
  91. package/dist/types/agent/tools/websearch.d.ts +17 -0
  92. package/dist/types/agent/tools/wikipedia.d.ts +7 -0
  93. package/dist/types/agent/tools-without-local-file-operands.d.ts +1 -0
  94. package/dist/types/agent/turn-runner.d.ts +36 -0
  95. package/dist/types/agent-messenger/config-dir.d.ts +19 -0
  96. package/dist/types/browser/dockerfile.d.ts +2 -0
  97. package/dist/types/browser/registry.d.ts +49 -0
  98. package/dist/types/bundled-plugins/bun-hygiene/policy.d.ts +18 -0
  99. package/dist/types/bundled-plugins/github-cli-auth/git-askpass.d.ts +5 -0
  100. package/dist/types/bundled-plugins/guard/keys.d.ts +6 -0
  101. package/dist/types/bundled-plugins/guard/policies/managed-config.d.ts +7 -0
  102. package/dist/types/bundled-plugins/guard/policies/memory-topics-delete.d.ts +11 -0
  103. package/dist/types/bundled-plugins/guard/policies/memory-topics-write.d.ts +7 -0
  104. package/dist/types/bundled-plugins/guard/policies/non-workspace-write.d.ts +9 -0
  105. package/dist/types/bundled-plugins/guard/policies/skill-authoring.d.ts +20 -0
  106. package/dist/types/bundled-plugins/guard/policies/uncommitted-changes.d.ts +12 -0
  107. package/dist/types/bundled-plugins/guard/policy.d.ts +11 -0
  108. package/dist/types/bundled-plugins/memory/secret-detector.d.ts +11 -0
  109. package/dist/types/bundled-plugins/memory/slug.d.ts +4 -0
  110. package/dist/types/bundled-plugins/security/permissions.d.ts +20 -0
  111. package/dist/types/bundled-plugins/security/policies/private-surface-read.d.ts +34 -0
  112. package/dist/types/bundled-plugins/security/policies/ssrf.d.ts +18 -0
  113. package/dist/types/bundled-plugins/security/policy.d.ts +4 -0
  114. package/dist/types/channels/adapter-namespace.d.ts +2 -0
  115. package/dist/types/channels/adapters/mention-hints.d.ts +12 -0
  116. package/dist/types/channels/adapters/webex-id-ref.d.ts +5 -0
  117. package/dist/types/channels/background-handoff.d.ts +56 -0
  118. package/dist/types/channels/background-obligations.d.ts +135 -0
  119. package/dist/types/channels/catch-up.d.ts +26 -0
  120. package/dist/types/channels/commands.d.ts +2 -0
  121. package/dist/types/channels/completion-claim.d.ts +20 -0
  122. package/dist/types/channels/continuation-willingness.d.ts +1 -0
  123. package/dist/types/channels/continuity-types.d.ts +75 -0
  124. package/dist/types/channels/describe-error.d.ts +1 -0
  125. package/dist/types/channels/engagement.d.ts +34 -0
  126. package/dist/types/channels/github-false-receipt.d.ts +20 -0
  127. package/dist/types/channels/github-repo.d.ts +2 -0
  128. package/dist/types/channels/github-rereview-guard.d.ts +24 -0
  129. package/dist/types/channels/github-review-check.d.ts +135 -0
  130. package/dist/types/channels/github-review-claim.d.ts +3 -0
  131. package/dist/types/channels/github-review-turn-ledger.d.ts +71 -0
  132. package/dist/types/channels/github-review-verdict-coordinator.d.ts +117 -0
  133. package/dist/types/channels/github-token-bridge.d.ts +20 -0
  134. package/dist/types/channels/github-verdict-activity.d.ts +12 -0
  135. package/dist/types/channels/inbound-journal.d.ts +272 -0
  136. package/dist/types/channels/last-alive.d.ts +3 -0
  137. package/dist/types/channels/membership-cache.d.ts +27 -0
  138. package/dist/types/channels/membership.d.ts +21 -0
  139. package/dist/types/channels/outbound-flood-filter.d.ts +7 -0
  140. package/dist/types/channels/participants.d.ts +4 -0
  141. package/dist/types/channels/persistence.d.ts +32 -0
  142. package/dist/types/channels/recovery-notice.d.ts +26 -0
  143. package/dist/types/channels/recovery-outbox.d.ts +58 -0
  144. package/dist/types/channels/router.d.ts +798 -0
  145. package/dist/types/channels/schema.d.ts +501 -0
  146. package/dist/types/channels/session-handoff.d.ts +58 -0
  147. package/dist/types/channels/session-search.d.ts +29 -0
  148. package/dist/types/channels/types.d.ts +414 -0
  149. package/dist/types/channels/waiting-reactions.d.ts +25 -0
  150. package/dist/types/cli/builtins.d.ts +2 -0
  151. package/dist/types/cli/command-meta.d.ts +9 -0
  152. package/dist/types/coding-agent/broker-body.d.ts +7 -0
  153. package/dist/types/coding-agent/broker.d.ts +22 -0
  154. package/dist/types/coding-agent/claude.d.ts +22 -0
  155. package/dist/types/coding-agent/codex.d.ts +19 -0
  156. package/dist/types/coding-agent/index.d.ts +71 -0
  157. package/dist/types/coding-agent/omo-state.d.ts +2 -0
  158. package/dist/types/coding-agent/omo-stream.d.ts +22 -0
  159. package/dist/types/coding-agent/omo.d.ts +133 -0
  160. package/dist/types/coding-agent/runner.d.ts +35 -0
  161. package/dist/types/coding-agent/tool.d.ts +27 -0
  162. package/dist/types/coding-agent/worktree.d.ts +22 -0
  163. package/dist/types/commands/index.d.ts +45 -0
  164. package/dist/types/config/config.d.ts +814 -0
  165. package/dist/types/config/index.d.ts +3 -0
  166. package/dist/types/config/model-overrides.d.ts +3 -0
  167. package/dist/types/config/providers.d.ts +1456 -0
  168. package/dist/types/config/reloadable.d.ts +9 -0
  169. package/dist/types/container/agent-operation-lock.d.ts +31 -0
  170. package/dist/types/container/build-cache.d.ts +39 -0
  171. package/dist/types/container/compose-project.d.ts +1 -0
  172. package/dist/types/container/controller.d.ts +25 -0
  173. package/dist/types/container/docker-app.d.ts +23 -0
  174. package/dist/types/container/exit-reason.d.ts +10 -0
  175. package/dist/types/container/index.d.ts +14 -0
  176. package/dist/types/container/log-archive.d.ts +68 -0
  177. package/dist/types/container/log-colors.d.ts +3 -0
  178. package/dist/types/container/log-timestamps.d.ts +9 -0
  179. package/dist/types/container/logs.d.ts +37 -0
  180. package/dist/types/container/memory-limit.d.ts +13 -0
  181. package/dist/types/container/memory-oversubscription.d.ts +20 -0
  182. package/dist/types/container/oom-events.d.ts +18 -0
  183. package/dist/types/container/port.d.ts +18 -0
  184. package/dist/types/container/require-running.d.ts +16 -0
  185. package/dist/types/container/restart.d.ts +32 -0
  186. package/dist/types/container/shared.d.ts +93 -0
  187. package/dist/types/container/shell.d.ts +35 -0
  188. package/dist/types/container/start.d.ts +144 -0
  189. package/dist/types/container/stats.d.ts +31 -0
  190. package/dist/types/container/status.d.ts +25 -0
  191. package/dist/types/container/stop.d.ts +24 -0
  192. package/dist/types/container/tool-oom-priority.d.ts +4 -0
  193. package/dist/types/container/verify-running.d.ts +49 -0
  194. package/dist/types/cron/consumer.d.ts +42 -0
  195. package/dist/types/cron/count-state.d.ts +24 -0
  196. package/dist/types/cron/index.d.ts +21 -0
  197. package/dist/types/cron/list.d.ts +33 -0
  198. package/dist/types/cron/reloadable.d.ts +11 -0
  199. package/dist/types/cron/scheduler.d.ts +51 -0
  200. package/dist/types/cron/schema.d.ts +108 -0
  201. package/dist/types/dependencies/bin-resolver.d.ts +28 -0
  202. package/dist/types/dependencies/bins.d.ts +22 -0
  203. package/dist/types/dependencies/index.d.ts +2 -0
  204. package/dist/types/git/bound-gc-config.d.ts +4 -0
  205. package/dist/types/git/hookless.d.ts +1 -0
  206. package/dist/types/git/reconcile-ignored.d.ts +13 -0
  207. package/dist/types/git/resolve-agent-git.d.ts +8 -0
  208. package/dist/types/git/resolve-identity.d.ts +10 -0
  209. package/dist/types/git/run.d.ts +24 -0
  210. package/dist/types/git/system-commit.d.ts +2 -0
  211. package/dist/types/hostd/client.d.ts +13 -0
  212. package/dist/types/hostd/models.d.ts +1 -0
  213. package/dist/types/hostd/paths.d.ts +17 -0
  214. package/dist/types/hostd/protocol.d.ts +93 -0
  215. package/dist/types/hostd/spawn.d.ts +17 -0
  216. package/dist/types/hostd/version.d.ts +18 -0
  217. package/dist/types/init/auto-upgrade.d.ts +41 -0
  218. package/dist/types/init/cli-version.d.ts +7 -0
  219. package/dist/types/init/dockerfile.d.ts +34 -0
  220. package/dist/types/init/ensure-deps.d.ts +17 -0
  221. package/dist/types/init/env-file.d.ts +3 -0
  222. package/dist/types/init/gitignore.d.ts +5 -0
  223. package/dist/types/init/local-source-stamp.d.ts +3 -0
  224. package/dist/types/init/packagejson.d.ts +7 -0
  225. package/dist/types/init/paths.d.ts +3 -0
  226. package/dist/types/init/reconcile-plugin-deps.d.ts +13 -0
  227. package/dist/types/init/run-bun-install.d.ts +16 -0
  228. package/dist/types/init/windows-dev-link.d.ts +8 -0
  229. package/dist/types/mcp/catalog.d.ts +7 -0
  230. package/dist/types/mcp/client.d.ts +58 -0
  231. package/dist/types/mcp/manager.d.ts +56 -0
  232. package/dist/types/mcp/tools.d.ts +23 -0
  233. package/dist/types/models/embedding-model.d.ts +20 -0
  234. package/dist/types/models/transformers-version.d.ts +1 -0
  235. package/dist/types/network/internal-destinations.d.ts +29 -0
  236. package/dist/types/operations/classify-tool-outcome.d.ts +35 -0
  237. package/dist/types/operations/incidents.d.ts +47 -0
  238. package/dist/types/operations/index.d.ts +3 -0
  239. package/dist/types/operations/remediations.d.ts +25 -0
  240. package/dist/types/path-safety/real-intended-path.d.ts +9 -0
  241. package/dist/types/permissions/builtins.d.ts +25 -0
  242. package/dist/types/permissions/grant.d.ts +19 -0
  243. package/dist/types/permissions/index.d.ts +6 -0
  244. package/dist/types/permissions/match-rule.d.ts +28 -0
  245. package/dist/types/permissions/permissions.d.ts +42 -0
  246. package/dist/types/permissions/resolve.d.ts +25 -0
  247. package/dist/types/permissions/schema.d.ts +14 -0
  248. package/dist/types/plugin/context.d.ts +20 -0
  249. package/dist/types/plugin/core-tool-names.d.ts +4 -0
  250. package/dist/types/plugin/define.d.ts +46 -0
  251. package/dist/types/plugin/hooks.d.ts +52 -0
  252. package/dist/types/plugin/index.d.ts +11 -0
  253. package/dist/types/plugin/load-skill.d.ts +14 -0
  254. package/dist/types/plugin/loader.d.ts +25 -0
  255. package/dist/types/plugin/manager.d.ts +42 -0
  256. package/dist/types/plugin/registry.d.ts +73 -0
  257. package/dist/types/plugin/skills.d.ts +11 -0
  258. package/dist/types/plugin/types.d.ts +336 -0
  259. package/dist/types/plugin/zod-introspect.d.ts +11 -0
  260. package/dist/types/reload/client.d.ts +11 -0
  261. package/dist/types/reload/docker-exec-client.d.ts +11 -0
  262. package/dist/types/reload/format.d.ts +2 -0
  263. package/dist/types/reload/index.d.ts +6 -0
  264. package/dist/types/reload/recover.d.ts +22 -0
  265. package/dist/types/reload/registry.d.ts +10 -0
  266. package/dist/types/reload/types.d.ts +25 -0
  267. package/dist/types/role-claim/client.d.ts +20 -0
  268. package/dist/types/role-claim/code.d.ts +4 -0
  269. package/dist/types/role-claim/controller.d.ts +59 -0
  270. package/dist/types/role-claim/index.d.ts +6 -0
  271. package/dist/types/role-claim/match-rule.d.ts +9 -0
  272. package/dist/types/role-claim/pending.d.ts +35 -0
  273. package/dist/types/role-claim/reload-after-claim.d.ts +16 -0
  274. package/dist/types/run/llm-fetch-observer.d.ts +50 -0
  275. package/dist/types/sandbox/availability.d.ts +21 -0
  276. package/dist/types/sandbox/build.d.ts +7 -0
  277. package/dist/types/sandbox/canonical-secrets.d.ts +8 -0
  278. package/dist/types/sandbox/coding-agent.d.ts +20 -0
  279. package/dist/types/sandbox/dependency-bins.d.ts +19 -0
  280. package/dist/types/sandbox/dev-source.d.ts +4 -0
  281. package/dist/types/sandbox/env-exposure.d.ts +1 -0
  282. package/dist/types/sandbox/errors.d.ts +20 -0
  283. package/dist/types/sandbox/hidden-paths.d.ts +11 -0
  284. package/dist/types/sandbox/index.d.ts +14 -0
  285. package/dist/types/sandbox/package-install.d.ts +1 -0
  286. package/dist/types/sandbox/policy.d.ts +71 -0
  287. package/dist/types/sandbox/privileged-runtime.d.ts +13 -0
  288. package/dist/types/sandbox/quote.d.ts +2 -0
  289. package/dist/types/sandbox/runtime-private.d.ts +1 -0
  290. package/dist/types/sandbox/session-tmp.d.ts +6 -0
  291. package/dist/types/sandbox/symlinks.d.ts +6 -0
  292. package/dist/types/sandbox/writable-zones.d.ts +15 -0
  293. package/dist/types/secrets/coding-agent-auth.d.ts +25 -0
  294. package/dist/types/secrets/defaults.d.ts +21 -0
  295. package/dist/types/secrets/export-github-cli-store.d.ts +22 -0
  296. package/dist/types/secrets/hydrate.d.ts +7 -0
  297. package/dist/types/secrets/index.d.ts +7 -0
  298. package/dist/types/secrets/provision-github-cli-store.d.ts +45 -0
  299. package/dist/types/secrets/refresh-provider-oauth.d.ts +22 -0
  300. package/dist/types/secrets/resolve.d.ts +14 -0
  301. package/dist/types/secrets/schema.d.ts +840 -0
  302. package/dist/types/secrets/storage.d.ts +56 -0
  303. package/dist/types/shared/host-locale.d.ts +1 -0
  304. package/dist/types/shared/index.d.ts +5 -0
  305. package/dist/types/shared/local-time.d.ts +4 -0
  306. package/dist/types/shared/platform.d.ts +2 -0
  307. package/dist/types/shared/protocol.d.ts +424 -0
  308. package/dist/types/shared/style-text.d.ts +3 -0
  309. package/dist/types/shared/wsl.d.ts +17 -0
  310. package/dist/types/stream/broker.d.ts +2 -0
  311. package/dist/types/stream/index.d.ts +2 -0
  312. package/dist/types/stream/types.d.ts +71 -0
  313. package/package.json +13 -6
  314. package/scripts/build-plugin-types.ts +105 -0
  315. package/scripts/check-plugin-sdk.ts +111 -0
  316. package/scripts/dump-system-prompt.ts +52 -110
  317. package/scripts/require-parallel.ts +5 -32
  318. package/src/agent/guard-types.ts +3 -0
  319. package/src/agent/guards.ts +4 -0
  320. package/src/agent/idle-compaction.ts +174 -0
  321. package/src/agent/index.ts +210 -80
  322. package/src/agent/live-sessions.ts +2 -2
  323. package/src/agent/live-subagents.ts +20 -0
  324. package/src/agent/multimodal/look-at.ts +22 -9
  325. package/src/agent/plugin-tools.ts +66 -12
  326. package/src/agent/prompt-cache-key.ts +42 -0
  327. package/src/agent/provider-error.ts +179 -10
  328. package/src/agent/restart-handoff/index.ts +7 -14
  329. package/src/agent/reviewer-activity.ts +68 -0
  330. package/src/agent/reviewer-bash-policy.ts +41 -1
  331. package/src/agent/session-origin.ts +58 -9
  332. package/src/agent/subagent-cache-keepalive.ts +198 -0
  333. package/src/agent/subagent-session.ts +6 -0
  334. package/src/agent/subagents.ts +59 -9
  335. package/src/agent/system-prompt.ts +68 -202
  336. package/src/agent/todo/continuation-policy.ts +12 -4
  337. package/src/agent/tool-file-safety.ts +119 -15
  338. package/src/agent/tool-not-found-nudge.ts +1 -1
  339. package/src/agent/tools/channel-edit.ts +20 -10
  340. package/src/agent/tools/channel-fetch-attachment.ts +12 -5
  341. package/src/agent/tools/channel-handoff.ts +72 -0
  342. package/src/agent/tools/channel-history-render.ts +2 -1
  343. package/src/agent/tools/channel-read.ts +57 -10
  344. package/src/agent/tools/channel-reply.ts +55 -30
  345. package/src/agent/tools/channel-send.ts +69 -19
  346. package/src/agent/tools/channel-session-search.ts +35 -0
  347. package/src/agent/tools/curl-impersonate.ts +22 -6
  348. package/src/agent/tools/ddg.ts +13 -5
  349. package/src/agent/tools/post-github-review.ts +77 -15
  350. package/src/agent/tools/skip-response.ts +2 -2
  351. package/src/agent/tools/spawn-subagent.ts +190 -23
  352. package/src/agent/tools/stream-snapshot.ts +15 -2
  353. package/src/agent/tools/subagent-access.ts +11 -4
  354. package/src/agent/tools/subagent-output.ts +8 -0
  355. package/src/browser/bsk-shim.mjs +74 -0
  356. package/src/browser/dockerfile.ts +84 -0
  357. package/src/browser/egress.ts +104 -0
  358. package/src/browser/managed-browser.ts +205 -0
  359. package/src/browser/registry.ts +110 -0
  360. package/src/browser/relay.ts +231 -0
  361. package/src/browser/sandbox-entry.ts +167 -0
  362. package/src/bundled-plugins/agent-browser/index.ts +2 -0
  363. package/src/bundled-plugins/backup/README.md +10 -9
  364. package/src/bundled-plugins/backup/runner.ts +140 -58
  365. package/src/bundled-plugins/backup/subagents.ts +58 -26
  366. package/src/bundled-plugins/browser-agent/browser-agent.ts +89 -0
  367. package/src/bundled-plugins/browser-agent/index.ts +12 -0
  368. package/src/bundled-plugins/doc-render/index.ts +0 -10
  369. package/src/bundled-plugins/doc-render/render.ts +83 -111
  370. package/src/bundled-plugins/doc-render/skills/typeclaw-render-pdf/SKILL.md +152 -257
  371. package/src/bundled-plugins/github-cli-auth/gh-command.ts +38 -2
  372. package/src/bundled-plugins/github-cli-auth/git-auth-diagnostic.ts +95 -0
  373. package/src/bundled-plugins/github-cli-auth/granted-push.ts +135 -0
  374. package/src/bundled-plugins/github-cli-auth/index.ts +158 -70
  375. package/src/bundled-plugins/github-cli-auth/review-account.ts +23 -0
  376. package/src/bundled-plugins/github-cli-auth/review-checkout.ts +9 -2
  377. package/src/bundled-plugins/github-cli-auth/review-recorder.ts +45 -7
  378. package/src/bundled-plugins/managed-browser/index.ts +74 -0
  379. package/src/bundled-plugins/managed-browser/skills/browser-use/browser-use/SKILL.md +27 -0
  380. package/src/bundled-plugins/managed-browser/skills/browserskill/browserskill/SKILL.md +28 -0
  381. package/src/bundled-plugins/managed-browser/skills/omowright/omowright/SKILL.md +40 -0
  382. package/src/bundled-plugins/operator/operator.ts +15 -4
  383. package/src/bundled-plugins/qa/index.ts +11 -0
  384. package/src/bundled-plugins/qa/qa.ts +160 -0
  385. package/src/bundled-plugins/qa/skills/qa-cli.ts +50 -0
  386. package/src/bundled-plugins/qa/skills/qa-general.ts +30 -0
  387. package/src/bundled-plugins/qa/skills/qa-http.ts +39 -0
  388. package/src/bundled-plugins/qa/skills/qa-pr.ts +51 -0
  389. package/src/bundled-plugins/qa/skills/qa-web.ts +49 -0
  390. package/src/bundled-plugins/reviewer/skills/code-review.ts +1 -1
  391. package/src/bundled-plugins/security/index.ts +103 -36
  392. package/src/bundled-plugins/security/policies/git-exfil.ts +24 -12
  393. package/src/bundled-plugins/security/policies/outbound-secret-scan.ts +1 -0
  394. package/src/channels/adapter-namespace.ts +13 -0
  395. package/src/channels/adapters/discord-bot-reactions.ts +18 -0
  396. package/src/channels/adapters/discord-bot.ts +219 -72
  397. package/src/channels/adapters/discord-reactions.ts +18 -0
  398. package/src/channels/adapters/discord.ts +114 -8
  399. package/src/channels/adapters/github/inbound.ts +103 -8
  400. package/src/channels/adapters/github/index.ts +267 -19
  401. package/src/channels/adapters/github/last-alive.ts +15 -0
  402. package/src/channels/adapters/github/outbound.ts +54 -18
  403. package/src/channels/adapters/github/pending-review-store.ts +141 -0
  404. package/src/channels/adapters/github/permission-guidance.ts +1 -0
  405. package/src/channels/adapters/github/reactions.ts +100 -0
  406. package/src/channels/adapters/github/reconcile-cooldown-store.ts +197 -67
  407. package/src/channels/adapters/github/reconcile-open-prs.ts +418 -33
  408. package/src/channels/adapters/github/recovery.ts +106 -0
  409. package/src/channels/adapters/github/review-check.ts +510 -0
  410. package/src/channels/adapters/github/review-submitter.ts +34 -2
  411. package/src/channels/adapters/instagram.ts +32 -14
  412. package/src/channels/adapters/kakaotalk.ts +22 -7
  413. package/src/channels/adapters/line.ts +18 -3
  414. package/src/channels/adapters/outbound-account.ts +20 -0
  415. package/src/channels/adapters/own-reactions.ts +66 -0
  416. package/src/channels/adapters/recovery-correlation.ts +214 -0
  417. package/src/channels/adapters/slack-attachment-download.ts +14 -3
  418. package/src/channels/adapters/slack-bot-author-resolver.ts +4 -3
  419. package/src/channels/adapters/slack-bot-channel-resolver.ts +9 -6
  420. package/src/channels/adapters/slack-bot-classify.ts +19 -11
  421. package/src/channels/adapters/slack-bot-dedupe.ts +111 -28
  422. package/src/channels/adapters/slack-bot-reactions.ts +18 -0
  423. package/src/channels/adapters/slack-bot-slash-commands.ts +3 -1
  424. package/src/channels/adapters/slack-bot.ts +424 -124
  425. package/src/channels/adapters/slack-classify.ts +26 -4
  426. package/src/channels/adapters/slack-inbound-revision.ts +96 -0
  427. package/src/channels/adapters/slack-reactions.ts +18 -0
  428. package/src/channels/adapters/slack-thread-ts.ts +6 -0
  429. package/src/channels/adapters/slack.ts +48 -3
  430. package/src/channels/adapters/teams.ts +14 -4
  431. package/src/channels/adapters/telegram-bot.ts +56 -10
  432. package/src/channels/adapters/webex-bot.ts +12 -2
  433. package/src/channels/adapters/webex.ts +12 -2
  434. package/src/channels/background-handoff.ts +434 -0
  435. package/src/channels/background-obligations.ts +893 -0
  436. package/src/channels/catch-up.ts +137 -0
  437. package/src/channels/continuation-willingness.ts +2 -2
  438. package/src/channels/continuity-types.ts +272 -0
  439. package/src/channels/engagement.ts +17 -1
  440. package/src/channels/github-false-receipt.ts +3 -3
  441. package/src/channels/github-rereview-guard.ts +9 -5
  442. package/src/channels/github-review-check.ts +598 -0
  443. package/src/channels/github-review-turn-ledger.ts +102 -28
  444. package/src/channels/github-review-verdict-coordinator.ts +72 -12
  445. package/src/channels/github-token-bridge.ts +35 -5
  446. package/src/channels/inbound-journal.ts +1738 -0
  447. package/src/channels/index.ts +6 -1
  448. package/src/channels/last-alive.ts +34 -0
  449. package/src/channels/manager.ts +25 -8
  450. package/src/channels/recovery-dispatcher.ts +264 -0
  451. package/src/channels/recovery-notice.ts +94 -0
  452. package/src/channels/recovery-outbox.ts +459 -0
  453. package/src/channels/router.ts +2951 -736
  454. package/src/channels/schema.ts +8 -1
  455. package/src/channels/session-handoff.fixture.ts +144 -0
  456. package/src/channels/session-handoff.ts +175 -0
  457. package/src/channels/session-search.ts +71 -0
  458. package/src/channels/subagent-completion-bridge.ts +17 -14
  459. package/src/channels/types.ts +133 -18
  460. package/src/channels/waiting-reactions.ts +664 -0
  461. package/src/cli/channel.ts +2 -3
  462. package/src/cli/compose.ts +7 -4
  463. package/src/cli/hostd.ts +49 -3
  464. package/src/cli/init.ts +2 -3
  465. package/src/cli/inspect.ts +11 -14
  466. package/src/cli/model.ts +132 -3
  467. package/src/coding-agent/broker-body.ts +38 -0
  468. package/src/coding-agent/broker.ts +290 -0
  469. package/src/coding-agent/claude.ts +95 -0
  470. package/src/coding-agent/codex.ts +104 -0
  471. package/src/coding-agent/index.ts +512 -0
  472. package/src/coding-agent/omo-state.ts +69 -0
  473. package/src/coding-agent/omo-stream.ts +138 -0
  474. package/src/coding-agent/omo.ts +192 -0
  475. package/src/coding-agent/runner.ts +285 -0
  476. package/src/coding-agent/tool.ts +62 -0
  477. package/src/coding-agent/worktree.ts +355 -0
  478. package/src/compose/restart.ts +10 -3
  479. package/src/compose/start.ts +20 -3
  480. package/src/config/config.ts +121 -25
  481. package/src/config/model-overrides.ts +59 -0
  482. package/src/config/models-mutation.ts +185 -2
  483. package/src/config/providers-mutation.ts +12 -4
  484. package/src/config/providers.ts +71 -9
  485. package/src/container/exit-reason.ts +44 -0
  486. package/src/container/index.ts +5 -0
  487. package/src/container/log-archive.ts +51 -13
  488. package/src/container/memory-limit.ts +1 -1
  489. package/src/container/memory-oversubscription.ts +36 -6
  490. package/src/container/oom-events.ts +86 -0
  491. package/src/container/restart.ts +2 -0
  492. package/src/container/shared.ts +8 -1
  493. package/src/container/start.ts +120 -17
  494. package/src/container/stop.ts +6 -2
  495. package/src/container/tool-oom-priority.ts +32 -0
  496. package/src/cron/consumer.ts +10 -4
  497. package/src/cron/reloadable.ts +23 -2
  498. package/src/doctor/checks.ts +22 -8
  499. package/src/hostd/daemon.ts +33 -11
  500. package/src/hostd/spawn.ts +106 -5
  501. package/src/hostd/version.ts +20 -0
  502. package/src/hostd/watchdog.ts +241 -0
  503. package/src/init/auto-upgrade.ts +7 -1
  504. package/src/init/dockerfile.ts +112 -602
  505. package/src/init/index.ts +6 -6
  506. package/src/init/local-source-stamp.ts +68 -0
  507. package/src/init/models-dev.ts +4 -0
  508. package/src/init/validate-api-key.ts +3 -0
  509. package/src/mcp/client.ts +3 -1
  510. package/src/operations/classify-tool-outcome.ts +45 -1
  511. package/src/operations/incidents.ts +10 -5
  512. package/src/permissions/builtins.ts +7 -0
  513. package/src/permissions/permissions.ts +18 -9
  514. package/src/permissions/resolve.ts +7 -1
  515. package/src/plugin/context.ts +2 -0
  516. package/src/plugin/core-tool-names.ts +1 -1
  517. package/src/plugin/define.ts +1 -0
  518. package/src/plugin/hooks.ts +137 -0
  519. package/src/plugin/index.ts +7 -0
  520. package/src/plugin/manager.ts +4 -0
  521. package/src/plugin/types.ts +66 -1
  522. package/src/run/background-handoff-boot.ts +86 -0
  523. package/src/run/bundled-plugins.ts +6 -0
  524. package/src/run/index.ts +107 -97
  525. package/src/run/llm-fetch-observer.ts +12 -15
  526. package/src/run/resource-sample.ts +19 -0
  527. package/src/sandbox/build.ts +4 -0
  528. package/src/sandbox/canonical-secrets.ts +4 -0
  529. package/src/sandbox/coding-agent.ts +214 -0
  530. package/src/sandbox/dev-source.ts +26 -0
  531. package/src/sandbox/hidden-paths.ts +16 -2
  532. package/src/sandbox/policy.ts +1 -0
  533. package/src/sandbox/runtime-private.ts +4 -1
  534. package/src/secrets/coding-agent-auth.ts +97 -0
  535. package/src/secrets/index.ts +0 -16
  536. package/src/secrets/storage.ts +13 -0
  537. package/src/server/command-runner.ts +6 -2
  538. package/src/server/index.ts +101 -40
  539. package/src/skills/typeclaw-channel-github/SKILL.md +15 -13
  540. package/src/skills/typeclaw-claude-code/SKILL.md +25 -260
  541. package/src/skills/typeclaw-claude-code/references/auth-flow.md +7 -23
  542. package/src/skills/typeclaw-claude-code/references/headless-sessions.md +11 -0
  543. package/src/skills/typeclaw-claude-code/references/results-and-worktrees.md +13 -0
  544. package/src/skills/typeclaw-codex-cli/SKILL.md +35 -270
  545. package/src/skills/typeclaw-codex-cli/references/auth-flow.md +13 -20
  546. package/src/skills/typeclaw-codex-cli/references/headless-sessions.md +26 -0
  547. package/src/skills/typeclaw-codex-cli/references/results-and-worktrees.md +28 -0
  548. package/src/skills/typeclaw-config/SKILL.md +60 -26
  549. package/src/skills/typeclaw-config/references/dockerfile.md +14 -13
  550. package/src/skills/typeclaw-cron/SKILL.md +1 -1
  551. package/src/skills/typeclaw-github-contributing/SKILL.md +3 -3
  552. package/src/skills/typeclaw-memory/SKILL.md +3 -3
  553. package/src/skills/typeclaw-monorepo/SKILL.md +1 -1
  554. package/src/skills/typeclaw-omo-cli/SKILL.md +52 -0
  555. package/src/skills/typeclaw-omo-cli/references/auth-flow.md +11 -0
  556. package/src/skills/typeclaw-omo-cli/references/headless-sessions.md +11 -0
  557. package/src/skills/typeclaw-omo-cli/references/results-and-worktrees.md +23 -0
  558. package/src/skills/typeclaw-permissions/SKILL.md +7 -7
  559. package/src/skills/typeclaw-plugins/SKILL.md +15 -15
  560. package/src/skills/typeclaw-skills/SKILL.md +19 -2
  561. package/src/skills/typeclaw-troubleshooting/SKILL.md +26 -2
  562. package/typeclaw.schema.json +448 -6
  563. package/src/bundled-plugins/doc-render/templates/lib.typ +0 -339
  564. package/src/bundled-plugins/github-cli-auth/gh-store.ts +0 -733
  565. package/src/secrets/claude-credentials-json.ts +0 -129
  566. package/src/secrets/codex-auth-json.ts +0 -102
  567. package/src/secrets/export-claude-credentials-file.ts +0 -270
  568. package/src/secrets/export-codex-auth-file.ts +0 -250
  569. package/src/skills/typeclaw-claude-code/references/stop-hook.md +0 -101
  570. package/src/skills/typeclaw-claude-code/references/tmux-driving.md +0 -243
  571. package/src/skills/typeclaw-codex-cli/references/stop-hook.md +0 -92
  572. package/src/skills/typeclaw-codex-cli/references/tmux-driving.md +0 -239
@@ -1,281 +1,46 @@
1
1
  ---
2
2
  name: typeclaw-claude-code
3
- description: Use this skill whenever you decide to delegate substantial coding or code-analysis work to Claude Code (Anthropic's official coding-agent CLI). Triggers include "use Claude Code", "ask Claude Code", "delegate to claude", "claude cli", "have claude do it", any task where you want a more capable agent than yourself, and any time you're about to run `claude` from a shell. Read it before you spawn the CLI — Claude Code is a TTY-only TUI in interactive mode (you must drive it through tmux, not pipes), it operates inside a dedicated `git worktree` checkout under `/tmp/` so its commits never pollute the agent folder, and you detect "turn done" through a `Stop` hook that writes a sentinel file. Skipping this skill means you'll either fall back to `claude -p` (which strips plan mode and sub-agents), let claude mutate the live agent checkout (which loses you the rollback safety), or try to parse the TUI buffer with capture-pane heuristics (fragile, version-locked).
3
+ description: Use for explicit Claude Code delegation, substantial coding or analysis suited to Claude Code, and before invoking claude. Uses TypeClaw's brokered headless runner with a persistent isolated worktree, not tmux or credential profiles.
4
4
  ---
5
5
 
6
- # typeclaw-claude-code
6
+ # Delegate to Claude Code
7
7
 
8
- > **Current security boundary:** authenticated Claude Code delegation is unavailable from model-driven TypeClaw tools. The bash sandbox never receives Anthropic keys, OAuth tokens, or Claude credential profiles, regardless of role. Do not start the tmux/worktree delegation flow for work that requires authentication. A direct operator may authenticate and run Claude Code themselves from the host side, outside the model tool boundary. The mechanics below are retained for unauthenticated diagnostics and for a future explicitly brokered runtime, not as a credential workaround.
9
-
10
- You can delegate work to Claude Code, Anthropic's official coding agent. The agent runs as an interactive TUI: it plans, uses sub-agents, edits files, runs tools — the full loop. You drive it through tmux because your own process has no TTY, you isolate it in a dedicated `git worktree` so its experiments never touch the live agent checkout, and you detect "turn done" through a `Stop` hook that writes a sentinel file (not by parsing the TUI buffer).
11
-
12
- This skill is for the case where Claude Code is the right tool: hard architecture work, multi-file refactors, deep code analysis, a second-opinion read on something you wrote. It is **not** for trivial edits — the round-trip cost (worktree setup + process spawn + auth check + TUI init + at least one full Claude turn) is 15–45 seconds and several thousand tokens of someone else's context window. Do trivial edits yourself.
13
-
14
- ## Run the delegation inside `operator`, not inline
15
-
16
- Once you've decided Claude Code is the right tool, spawn the bundled `operator` subagent to do the actual driving — don't run the worktree setup, the tmux session, the polling loop, the multi-turn decision loop, and the cleanup inline in your own context. The whole loop typically takes several minutes and produces large amounts of intermediate output (TUI buffer captures, Stop sentinels per turn, JSONL transcript references); running it inline blocks the user from talking to you and burns through your context window before you ever get to the synthesis step. `operator` is write-capable and runs the same loop, then returns a clean final report (what claude produced, what `git diff main..cc-<id>` shows, what you should review). You ship the worktree, the prompt, and the safety constraints to operator; operator ships you back the diff and the summary.
17
-
18
- Exception: a quick unauthenticated sanity ping (`claude --version` to check the binary exists). Do it inline. Do not probe authentication state. The "spawn through operator" rule applies to anything that runs `claude` itself as an interactive TUI.
19
-
20
- ## When to delegate to Claude Code
21
-
22
- Use Claude Code for:
23
-
24
- - **Multi-file refactors** that need a holistic plan before any edit lands.
25
- - **Code analysis** the user wants done thoroughly — "review this module", "find the bug in this 800-line file", "explain why X is slow".
26
- - **Implementations you're unsure about** where a more capable model would catch issues you'd miss.
27
- - **A second pair of eyes** on a design you've already drafted, especially when the user asks for one.
28
-
29
- Do **not** use Claude Code for:
30
-
31
- - One-line edits, typo fixes, single-function tweaks.
32
- - Anything where the user is watching your tool calls and wants to see each step — Claude's intermediate output is captured but not streamed back to the user.
33
- - Tasks that depend on context you haven't extracted yet. Claude won't have repo-wide context either; you have to brief it explicitly.
34
-
35
- ## Authentication boundary
36
-
37
- Authentication is an **operator-owned host action**. Model-driven tools cannot read or write `.env`, `secrets.json`, `auth.json`, `~/.claude/.credentials.json`, or the persistent credential directories, and must never ask a user to paste an API key or OAuth token into chat.
38
-
39
- Even when TypeClaw's trusted runtime has provider credentials, model-driven bash does not inherit them and cannot open the exported profile. There is no readiness check that turns authenticated delegation on.
40
-
41
- Stop and tell the operator that they must authenticate and invoke Claude Code directly from the **host side**. Do not promise that `typeclaw restart`, a role grant, a guard acknowledgement, or an existing provider login will make authenticated model-driven delegation available. Any direct Claude Code login or token setup must be completed entirely by the operator; do not request its output.
42
-
43
- If Claude Code presents an auth prompt or API-key confirmation that would require entering or inspecting a credential, abort and report that host-side authentication is required. Never transmit a credential through tmux, a prompt, a tool argument, or a file writable by the model. See `references/auth-flow.md`.
44
-
45
- ### Cost-cap warning
46
-
47
- Interactive-mode Claude Code has **no built-in spend cap** — `--max-budget-usd` only works in `-p` mode, which is not what we use here. If the user is on the API-key path, recommend setting a workspace spend limit in the Anthropic Console; that's the only safety net. If they're on OAuth (subscription), usage is bounded by the subscription's monthly Agent SDK credit pool. Tell them once before the first delegation so it's not a surprise.
8
+ Brief the task, repository, constraints, and acceptance checks. Use this for substantial implementations, investigations, refactors, or a second opinion; do trivial edits directly.
48
9
 
49
10
  ## Prerequisites
50
11
 
51
- Before you spawn `claude` for any real work:
52
-
53
- - **`docker.file.claudeCode: true`** in `typeclaw.json`. Verify with `which claude`; if missing, the toggle isn't on. Tell the user to enable it and `typeclaw start --build`.
54
- - **`docker.file.tmux: true`** (default `true`, but check). Verify with `which tmux`.
55
- - **No authenticated model-driven path.** If the task requires a Claude account, stop and hand execution to the direct host-side operator. Do not probe env vars or credential files.
56
- - **Onboarding pre-seeded.** The Dockerfile layer writes non-secret onboarding preferences. A workspace-trust dialog may still appear. Any API-key or sign-in dialog means the command requires authentication that model-driven tools cannot receive: abort rather than navigating it.
57
- - **Agent folder is a git repo.** Verify with `git -C /agent rev-parse --is-inside-work-tree`. The worktree model below requires it. If the user's agent folder somehow isn't a repo (rare — `typeclaw init` scaffolds one), tell them to `git init && git add -A && git commit -m "initial"` first.
58
- - **No uncommitted changes that you care about.** `git -C /agent status --porcelain` should be clean, or you should be willing to set the working tree aside before delegating. The worktree is a separate checkout, so claude can't see your uncommitted changes — meaning claude operates on the last committed state. If the user wants claude to work with in-progress edits, commit them first (even on a WIP branch).
59
-
60
- If any prerequisite is missing, stop and surface the gap to the user. Do not try to install `claude` yourself in the running container — the install belongs in the Dockerfile layer, not at runtime.
61
-
62
- ## Create the worktree
63
-
64
- Each delegation runs inside a dedicated `git worktree` checkout under `/tmp/`. This is the load-bearing isolation that makes the rest of the skill safe:
65
-
66
- - **Claude can edit, commit, reset, run tests** — none of it touches the agent folder's live working tree or its main branch pointer.
67
- - **You get perfect introspection.** `git diff` between claude's branch and your main checkout shows exactly what claude changed; `git log` shows how it got there.
68
- - **Cleanup is bounded.** When you're done, you remove the worktree and its branch; nothing persists on disk except deliberately cherry-picked commits.
69
- - **The agent folder's `git status` stays clean during delegation** — the user can keep working on their own checkout while claude operates in parallel.
70
-
71
- ### Setup
72
-
73
- Pick a task id (short hex string or `verb-noun` like `refactor-auth`) and create the worktree:
74
-
75
- ```sh
76
- git -C /agent worktree add -b cc-<task-id> /tmp/cc-<task-id> HEAD
77
- cd /tmp/cc-<task-id>
78
- ```
79
-
80
- This creates:
81
-
82
- - A new branch `cc-<task-id>` rooted at the agent folder's current `HEAD`.
83
- - A new working tree at `/tmp/cc-<task-id>/` containing every file from that commit.
84
- - An entry in `/agent/.git/worktrees/cc-<task-id>/` that ties the two together.
85
-
86
- The worktree shares the agent folder's `.git` directory but has its own `HEAD`, index, and working tree. Branch state lives in `/agent/.git/refs/heads/cc-<task-id>` regardless of where the worktree itself lives on disk.
87
-
88
- No per-task hook config is needed — the Stop and SessionStart hooks are wired globally at Dockerfile-build time (see "The Stop hook" below). Your worktree just becomes the cwd when you spawn `claude`; the global hooks write per-session files into `$PWD` (which `tmux new-session -c /tmp/cc-<id>` sets to the worktree).
89
-
90
- ```
91
- /tmp/cc-<task-id>/
92
- ├── .session-id # written by SessionStart hook (fast path; may not appear before trust is accepted)
93
- ├── sentinel-<uuid>.json # written by Stop hook per turn
94
- ├── .done-<uuid> # flag file written by Stop hook per turn
95
- └── ... # plus every file from the agent folder's HEAD
96
- ```
97
-
98
- ### Why `/tmp/`, not `workspace/`?
99
-
100
- `workspace/` is the agent folder's gitignored scratch zone — fine for one-off scripts. But a `git worktree` is a _checkout_, not scratch: it carries an index, refs in `/agent/.git/worktrees/`, and (briefly) shares working-tree state with the main checkout. Putting it under `workspace/` would mean the agent folder contains a worktree of itself, which works mechanically but is recursive and confusing (nested worktrees? infinite recursion if claude does `git status`?). `/tmp/cc-<id>/` keeps the worktree clearly outside the agent folder. It's also genuinely ephemeral — `/tmp/` is tmpfs-ish, survives container life but never enters git history or backups.
101
-
102
- ## The Stop hook
103
-
104
- Claude Code fires a `Stop` hook every time it finishes responding — turn-end, not session-end. The hook runs an arbitrary shell command with the lifecycle event payload (JSON) on stdin. We use this as the done-signal: the hook writes the payload to `sentinel.json` and `touch`es `.done`, and your polling loop watches for `.done`.
105
-
106
- **The hook is pre-baked into the container image.** When `docker.file.claudeCode: true`, the Dockerfile install layer writes TWO hook scripts and a settings file:
107
-
108
- - `/usr/local/bin/typeclaw-cc-session-start-hook` — fires once at session start. Reads the SessionStart event JSON from stdin, extracts `session_id`, validates it as a UUID, and writes `$PWD/.session-id` (atomically, temp-then-rename) containing that UUID. This is how the operator learns the session UUID — the only reliable way, because `claude --session-id <uuid>` does NOT propagate to hook payloads in interactive mode (anthropics/claude-code#44607).
109
- - `/usr/local/bin/typeclaw-cc-stop-hook` — fires every turn. Reads the Stop event JSON from stdin, extracts the same `session_id`, and writes per-session files: `$PWD/sentinel-<session_id>.json` atomically and `$PWD/.done-<session_id>`. The script uses `$PWD` (the literal cwd Claude Code was invoked with — set by the operator's `tmux new-session -c /tmp/cc-<id>`) rather than Claude Code's `$CLAUDE_PROJECT_DIR`, which resolves to the _git root of cwd_ and inside a worktree returns the main repo's path, not the worktree path. See the `TYPECLAW_CC_STOP_HOOK_PATH` comment block in `src/init/dockerfile.ts` for the upstream-bug citations (anthropics/claude-code#27343, #44450) that drove that choice.
110
- - `~/.claude/settings.json` — user-level (global) Claude Code settings that register both hooks for every `claude` invocation in the container. Built at build time via `JSON.stringify` so the shape never drifts. Both hooks use exec form (`args: []` present) so Claude Code invokes them via `execvp` directly (kernel-handled shebang, no shell tokenization).
111
-
112
- You do **not** write any of these files. The previous version of this skill had you `mkdir -p .claude && cat > .claude/settings.json …` per worktree; that step is removed. The shape of the JSON used to be the single most failure-prone part of a delegation (Claude Code silently ignores unknown keys, so wrong-shape configs like `{"hooks": {"onStop": "./script.sh"}}` would let the polling loop run to its wall-clock budget without ever firing the hook), and the only reliable fix is to keep the JSON out of LLM hands entirely.
113
-
114
- ### Per-session filenames — race safety
115
-
116
- The sentinel and `.done` filenames carry the session UUID — `sentinel-<uuid>.json` and `.done-<uuid>` — so two `claude` sessions sharing a cwd cannot collide on a fixed `sentinel.json`. You learn the UUID one of two ways:
117
-
118
- 1. **Fast path: read `.session-id` after spawning claude.** The SessionStart hook writes it on session start. Works for sessions that don't hit the workspace-trust dialog (re-attached worktrees, etc.).
119
- 2. **Discovery path: read it from the first Stop sentinel.** After sending the first prompt, glob `.done-*` for new files. The first one's UUID becomes `cc_session_id`. This path is required for fresh worktrees because per anthropics/claude-code#11519, **SessionStart is skipped entirely while workspace trust is pending** — and EVERY fresh worktree starts with the trust dialog pending. The fast path never wins on a first delegation.
120
-
121
- In both cases, **`cc_session_id` can ROTATE mid-delegation**. Per anthropics/claude-code#29094, `SessionStart` with `source: "compact"` is a NEW session linked via `parent_session_id`. So a long claude session that auto-compacts will start emitting Stop events with a DIFFERENT session_id. Your polling loop must handle this: if you see a new `.done-<different-uuid>` appear, update `cc_session_id` to the new value.
122
-
123
- **Do NOT use `claude --session-id <uuid>`.** Per anthropics/claude-code#44607, the flag works only in `-p` (print) mode; in interactive mode it sets a telemetry ID while the CLI generates its own UUID for the transcript and for hook payloads. The pre-generated UUID and the hook's UUID don't match, the polling loop watches a file that never appears, and the loop times out. If you find yourself reaching for `--session-id`, stop — let claude pick its own UUID and learn it via discovery.
124
-
125
- If you see `$PWD/.session-id` containing the literal string `malformed`, or `$PWD/sentinel-malformed.json` appearing instead of your expected file, a hook fired but couldn't extract a UUID-shape `session_id` from the event payload (malformed JSON, missing field, or a future upstream schema change). Read the file to diagnose; surface to the user.
126
-
127
- ### Verifying the global hooks
128
-
129
- Verify both hooks are wired correctly in the container before the first delegation of a session:
130
-
131
- ```sh
132
- test -x /usr/local/bin/typeclaw-cc-stop-hook && \
133
- test -x /usr/local/bin/typeclaw-cc-session-start-hook && \
134
- jq -e '
135
- .hooks.Stop[0].hooks[0].command == "/usr/local/bin/typeclaw-cc-stop-hook"
136
- and .hooks.Stop[0].hooks[0].args == []
137
- and .hooks.SessionStart[0].hooks[0].command == "/usr/local/bin/typeclaw-cc-session-start-hook"
138
- and .hooks.SessionStart[0].hooks[0].args == []
139
- ' "$HOME/.claude/settings.json"
140
- ```
141
-
142
- Three distinct failure modes if it fails:
143
-
144
- | Symptom | Cause | Remediation |
145
- | ---------------------------------------------------- | ------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
146
- | `test -x …` fails | Hook script missing | `docker.file.claudeCode` is off, or image built before this layer landed → `typeclaw start --build` |
147
- | Scripts present, `jq` fails | `$HOME/.claude/settings.json` was overwritten or bind-mounted | Check `cat ~/.claude/settings.json` for user-mounted config; if so, the operator's hooks won't fire and the delegation cannot proceed |
148
- | Scripts + settings correct, no sentinel ever appears | Hooks failing at runtime (trust skip, schema mismatch, permissions) | Inspect `ls -la /tmp/cc-<id>/.cc-*-in.*` to see if hooks fired at all, and read any `sentinel-malformed.json` for diagnostic |
149
-
150
- Don't try to write the hook config yourself — the operator subagent doesn't have the right tools to do it reliably, which is exactly the failure mode this layout was built to eliminate.
151
-
152
- The full schema of the Stop event (every field Claude Code populates, including `last_assistant_message` and `transcript_path`) is in `references/stop-hook.md`.
153
-
154
- ## Driving the session
155
-
156
- The minimum protocol — translate to your actual tool calls:
157
-
158
- 1. Create the worktree.
159
- 2. `tmux new-session -d -s cc-<id> -c /tmp/cc-<id> claude`. Do NOT pass `--session-id` — it doesn't propagate to hook payloads in interactive mode (see "Per-session filenames" above).
160
- 3. Wait ~3 seconds for the TUI to initialize.
161
- 4. **Clear startup dialogs (BEFORE sending the task prompt).** Even with `~/.claude.json` pre-seeded, claude can land on one or both pre-prompt modals. Run this as a **loop**, not a one-shot: clearing one dialog can immediately reveal the next, and you must keep polling until claude's actual input prompt is visible (it renders a bottom-of-pane input box with a `╭` / `╰` border). **Do NOT poll `.session-id` before this step** — per anthropics/claude-code#11519, SessionStart is suppressed while workspace trust is pending, so `.session-id` will not appear until you've accepted trust here.
162
-
163
- The two known modals, with the exact keystrokes for each (Claude Code's select widget does NOT wrap — pressing `Up` from the first option is a no-op, so the direction must match the dialog's option order):
164
- - **Custom API key or sign-in prompt** — abort the session and tell the direct operator to authenticate and run Claude Code host-side. Never accept the prompt or enter a credential.
165
-
166
- - **Workspace trust** — "Do you trust the files in this folder?" Fires on first launch in any new cwd, so every fresh `/tmp/cc-<id>/` worktree triggers it. Options are `[Yes, proceed, No, exit]` with focus on the first option (**Yes**) by default. Resolution: bare `tmux send-keys -t cc-<id> Enter` — no arrow key needed. Always verify the pane text matches the trust dialog before pressing Enter; a misidentified modal would submit a different default.
167
-
168
- Loop shape (translate to your tool calls):
169
- 1. Capture the last ~15 lines: `tmux capture-pane -t cc-<id> -p -S -15`.
170
-
171
- 5. If the capture contains an API-key or sign-in dialog → send `/exit` (or terminate the unauthenticated session if no input box is available), then report that the direct host-side operator must authenticate and run Claude Code. Never select a credential option or enter a key. 3. If the capture contains the trust dialog text → `send-keys Enter`, sleep 500ms, goto 1. 4. If the capture shows the input box (`╭` border on a bottom line, no dialog text above it) → ready; exit the loop. 5. Otherwise sleep 500ms, goto 1. Apply a wall-clock budget of ~10 seconds; if the loop hasn't reached step 4 by then, abort with `/exit` and surface to the user — claude is in a state this skill doesn't model.
172
-
173
- Do not use a fixed 2-second wait then send the prompt — cold-start and slow-disk cases can deliver a dialog at 2.5s+, and sending the task prompt into a modal corrupts the session.
174
-
175
- **Safety note**: accepting workspace trust on a fresh `/tmp/cc-<id>/` worktree is the right call **only when its `HEAD` is the intended clean state** — typically the agent folder's last good commit on a branch the user controls. If the user just merged a third-party PR, pulled a remote branch, or checked out an untrusted ref, the worktree carries that content too and "trusting" it gives claude tool access on potentially hostile code. Before auto-accepting trust, sanity-check: if the user hasn't said something equivalent to "delegate this to Claude Code", or if you're not confident the current `HEAD` is one the user authored or reviewed, surface the trust dialog to them instead. Do NOT extend even a legitimate trust acceptance to in-session permission prompts (Bash, Edit, etc.) — those still need per-turn judgment per the multi-turn decision loop below.
176
-
177
- 6. `tmux send-keys -t cc-<id> "<your prompt>" Enter`.
178
- 7. **Discover the session UUID from the newest unprocessed Stop sentinel.** Poll `/tmp/cc-<id>/.done-*` in a loop: each iteration, enumerate the files sorted by mtime (`ls -t`), filter out any UUIDs you've already processed (initially empty), and pick the first one whose UUID is a real hex UUID (not `malformed`). That UUID becomes `cc_session_id`. On every poll, also check `tmux has-session -t cc-<id>` — if the session died, claude crashed or auth failed. (Fast-path optimization: if `/tmp/cc-<id>/.session-id` happened to appear before the first prompt, you can use it instead and skip the glob — see `references/tmux-driving.md` for the fast-path snippet.) If the only marker that appears is `.done-malformed`, the Stop hook fired but couldn't extract a UUID-shape `session_id` from the payload — bail and surface to the user.
179
- 8. Read `/tmp/cc-<id>/sentinel-${cc_session_id}.json`, examine `last_assistant_message`, then `rm /tmp/cc-<id>/.done-${cc_session_id}` (the SPECIFIC file you just processed, NOT a glob — globbing wipes any in-flight new sentinel from a concurrent compact rotation).
180
- 9. Decide using the multi-turn loop below. **Track which UUIDs you've already processed.** On the next poll, again pick the newest unprocessed `.done-<uuid>`. If the UUID differs from the previous `cc_session_id`, claude has compacted (anthropics/claude-code#29094) — update `cc_session_id` to the new value and continue. Polling is edge-triggered: don't wait on `.done-${cc_session_id}` specifically, because if compact rotated the UUID, that file will never appear.
181
- 10. When done: `tmux send-keys -t cc-<id> "/exit" Enter && sleep 1 && tmux kill-session -t cc-<id>`.
182
-
183
- The full polling implementation, the ANSI-handling rules for `capture-pane` fallbacks, and the "tmux session died unexpectedly" recovery path are in `references/tmux-driving.md`.
184
-
185
- ## The multi-turn decision loop
186
-
187
- `Stop` fires every turn — including turns where claude paused to ask you a question, not just turns where claude finished the task. After every Stop sentinel, read `last_assistant_message` and decide:
188
-
189
- - **Ends with a question mark, or contains "Do you want me to", "Should I", "Could you clarify"** → claude is asking a clarifying question. Compose an answer from the original task brief and `send-keys` it back. Reset the loop: `rm /tmp/cc-<id>/.done-${cc_session_id}` (the SPECIFIC file you just processed), add that UUID to your processed set, then poll for the next newest unprocessed `.done-<uuid>`.
190
- - **Mentions a permission-style ask** ("May I run `<command>`?", "Allow me to edit `<file>`?") → answer per the task's safety constraints. If the constraint is unclear, abort with `/exit` and surface to the user — never invent a yes/no on the user's behalf for an unbounded operation.
191
- - **Looks like a final result** (code block + summary, or "Done.", "Here's the result.", "I've finished") → capture and `/exit`.
192
- - **Looks like a status update mid-tool-use** ("Let me check…", "Reading the file now…") → this is a spurious Stop (a Claude turn-boundary that isn't real task progress). `rm /tmp/cc-<id>/.done-${cc_session_id}`, add the UUID to your processed set, and keep polling.
193
-
194
- **Hard turn cap: 8 turns per delegation.** Beyond that, either the task is too complex to delegate cleanly or claude is stuck in a loop. Abort with `/exit`, capture what you have, surface to the user with: "Claude took 8 turns without finishing — here's what it produced, what do you want to do?"
195
-
196
- This loop is the most failure-prone part of the skill. If you find yourself uncertain whether a message is a question or a result, **default to surfacing to the user**, not to guessing. Wrong answers compound across turns.
197
-
198
- ## Capturing the output
199
-
200
- Four sources, in order of preference:
201
-
202
- 1. **`git diff /agent main..cc-<id>`** (run from `/agent`, or use the explicit worktree path). This is the killer feature of the worktree model — the exact set of changes claude made, branch-vs-branch. Use this for code-change tasks.
203
- 2. **`git log cc-<id> --oneline main..cc-<id>`** for how claude got there (the sequence of commits). Useful when claude broke a refactor into steps you want to attribute or cherry-pick.
204
- 3. **`sentinel-<cc_session_id>.json` from the final turn** (`last_assistant_message`). The narrative summary claude gave you. Use this for analysis tasks where the answer is prose, not code.
205
- 4. **The JSONL transcript** at `transcript_path` in the sentinel. The complete conversation including intermediate tool calls. Use when the diff/log aren't enough and you need to see how claude reasoned. Schema in `references/stop-hook.md`.
206
-
207
- For code-change tasks, the canonical pattern is:
208
-
209
- 1. Read `last_assistant_message` for the summary.
210
- 2. Run `git diff main..cc-<id> -- <files>` to see the actual changes.
211
- 3. Decide: are these changes good? If yes, either `git cherry-pick <commits>` onto the agent folder's branch OR copy the changes manually into the main checkout and commit there with proper attribution (per `typeclaw-git`).
212
- 4. Throw away the `cc-<id>` branch.
213
-
214
- Never paste Claude's output verbatim into your reply or a commit message. Summarize, attribute ("Claude Code's analysis: ..."), and stay accountable for the work. You delegated up; you didn't outsource ownership.
215
-
216
- ## Cleanup discipline
217
-
218
- Cleanup is git-aware: a worktree isn't just a directory. Three steps, in order:
219
-
220
- ```sh
221
- tmux kill-session -t cc-<id> 2>/dev/null || true
222
- git -C /agent worktree remove --force /tmp/cc-<id>
223
- git -C /agent branch -D cc-<id>
224
- ```
225
-
226
- - **`tmux kill-session`** first because claude might still be holding files open. `|| true` because a clean `/exit` already killed the session.
227
- - **`git worktree remove --force`** because the working tree may have dirty files (the sentinel, the hook script, claude's in-progress edits). `--force` skips the "uncommitted changes" check; this is correct here because we're explicitly discarding the worktree.
228
- - **`git branch -D cc-<id>`** to delete the branch ref. Without this, `cc-<id>` lingers in `git branch -a` indefinitely. `-D` (capital) because `cc-<id>` is unmerged into anything you care about.
12
+ The host operator enables `docker.file.claudeCode:true`, configures the Anthropic provider, and starts the rebuilt image. Use the tool's safe diagnostic to check readiness; never inspect credential files or environment values. Missing binary: ask for a host rebuild/restart. Missing or revoked authentication: host `typeclaw provider add anthropic`, then retry. See [auth-flow.md](references/auth-flow.md).
229
13
 
230
- Always do all three, including on failure paths. Orphan worktrees:
14
+ ## Run through an operator
231
15
 
232
- - Show up in `git worktree list` forever.
233
- - Cause `git status` in the agent folder to mention "another worktree exists at /tmp/cc-<id>" if you `cd` somewhere related.
234
- - Make the next delegation with the same task-id fail with "branch already exists".
16
+ The main agent spawns a background `operator` with the repository, task, constraints, and expected checks. The operator invokes `coding_agent` in the foreground. The existing subagent completion delivers the report while the main conversation stays responsive.
235
17
 
236
- Before starting a new delegation, check for orphans:
18
+ First run, with a compatible configured model:
237
19
 
238
- ```sh
239
- git -C /agent worktree list | grep cc-
240
- tmux ls 2>/dev/null | grep '^cc-'
20
+ ```json
21
+ {
22
+ "action": "run",
23
+ "engine": "claude",
24
+ "repo": "/agent",
25
+ "modelRef": "anthropic/claude-opus-5-5",
26
+ "mode": "code",
27
+ "prompt": "Implement the requested change and run its tests.",
28
+ "timeoutSeconds": 1800
29
+ }
241
30
  ```
242
31
 
243
- Kill anything you find first.
32
+ Record the returned `taskId`, `baseSha`, and `worktreePath`. The baseline is committed HEAD. Dirty source changes are excluded and reported; do not auto-commit or stage them to satisfy a prerequisite.
244
33
 
245
- ## When not to delegate
34
+ For planning use `mode:"plan"`; the worktree and its Git database are read-only. Continue with a new prompt and the same task ID, explicitly using `mode:"code"` for approved implementation. The runtime manages explicit CLI session resume and fresh invocation authority. Never select the latest session or pass your own CLI session identifier. See [headless-sessions.md](references/headless-sessions.md).
246
35
 
247
- A re-statement, because this is where the skill is most often misused:
36
+ ## Review, recover, dispose
248
37
 
249
- - **Trivial edits**: the round-trip cost dominates. Do it yourself.
250
- - **Tasks needing live user visibility**: claude's tool calls don't stream back through TypeClaw. The user sees a long pause, not progress. Use your own tools.
251
- - **Tasks where you don't have the context to brief claude**: spend tokens narrowing the problem first. A vague delegation produces a vague result.
252
- - **Any secret, including Anthropic credentials**: never pass it through the prompt or worktree. It would land in Claude's transcript and sentinels.
38
+ Inspect structured state, final message, changed-file inventory, and complete patch. A successful CLI turn is not proof that tests passed. If the answer asks a question, provide a follow-up prompt or ask the parent; do not classify completion by English keywords or poll for sentinels.
253
39
 
254
- ## Things you must not do
40
+ Read the full diff, including untracked/binary files, and run relevant checks before applying through ordinary tools. No automatic commit, merge, push, PR, or channel publication occurs.
255
41
 
256
- - **Do not use `claude -p` for delegation work.** The headless print mode strips plan mode, sub-agents, and the agent loop. The whole reason to delegate up is the loop. If you find yourself reaching for `-p`, the right answer is probably "do it yourself".
257
- - **Do not run `claude` directly inside `/agent`.** Always inside `/tmp/cc-<id>/`. Running claude in the agent folder lets it mutate the live working tree and break the user's session in flight.
258
- - **Do not skip the worktree.** Even for short delegations, the worktree is what gives you the `git diff` introspection and the rollback safety. Skipping it because "this one's small" is the path to claude accidentally committing on the wrong branch.
259
- - **Do not share a tmux session across two delegated tasks.** Each task needs its own worktree and its own tmux session. The hook config is global (`~/.claude/settings.json`), so sharing a worktree means two sessions race on the same `$PWD/.session-id` file. Per-session filenames (`sentinel-<uuid>.json`, `.done-<uuid>`) make per-turn artifacts safe across sessions but `.session-id` is fixed-name; the operator's discovery flow handles this by globbing `.done-*` anyway.
260
- - **Do not leave a tmux session, worktree, or branch alive after capturing the result.** All three need explicit teardown. Reusing them defeats the per-task isolation that makes the Stop hook reliable.
261
- - **Do not push claude's branch to a remote.** `cc-<id>` is throwaway. If something useful happened, cherry-pick onto a real branch first; don't push the experimental branch directly.
262
- - **Do not merge claude's branch into main without reviewing the diff.** The `git diff main..cc-<id>` is your review surface. Skipping the diff and merging blindly means you don't actually know what shipped.
263
- - **Do not commit `/tmp/cc-<id>/` artifacts back to the agent folder.** The sentinel, the hook script, the captured pane content are scratch — they live in `/tmp/`, they die with `worktree remove`.
264
- - **Do not paste Claude's output verbatim into a commit message or a user reply.** Summarize and attribute. You're accountable for the work you ship.
265
- - **Do not put `ANTHROPIC_API_KEY` or `CLAUDE_CODE_OAUTH_TOKEN` in `typeclaw.json`, a prompt, a worktree, or any model-accessible file.** Credential provisioning is direct-operator host work; the model does not edit `.env`.
266
- - **Do not poll the JSONL transcript directly as the done-signal.** The JSONL has documented race conditions (the file can be stale when `Stop` fires, or occasionally missing entirely). The sentinel is the reliable signal; the JSONL is for content, not lifecycle.
267
- - **Do not read, write, edit, parse, or verify `.env`, `secrets.json`, `auth.json`, `~/.claude/.credentials.json`, or any credential value.** These are outside the model-driven tool boundary; guard acknowledgements do not make credential handling acceptable.
268
- - **Do not run `claude setup-token` inside the container, and do not ask the user to paste its output.** Authentication remains entirely on the operator's host side.
269
- - **Do not ask for, receive, echo, log, or transcribe credentials.** If a user offers one, tell them not to send it and direct them to host-side setup.
270
- - **Do not invent answers to Claude's clarifying questions.** If you can't derive the answer from the original task brief, surface the question to the user. Wrong answers compound across multi-turn delegations.
271
- - **Do not exceed 8 turns per delegation.** Abort, capture what you have, surface. Long delegations almost always mean the task wasn't shaped right.
272
- - **Do not assume `claude` exists.** If `which claude` returns empty, the `docker.file.claudeCode` toggle isn't on. Tell the user, don't try to install it yourself.
42
+ After failure, timeout, cancellation, or restart, retain the partial work. `{"action":"result","taskId":"<returned UUID>"}` retrieves the authoritative receipt. Resume explicitly; do not silently start a replacement conversation. Discard only when no useful work will be lost: `{"action":"dispose","taskId":"<returned UUID>","discard":true}`. See [results-and-worktrees.md](references/results-and-worktrees.md).
273
43
 
274
- ## Cross-references
44
+ ## Credential boundary
275
45
 
276
- - **`references/auth-flow.md`** — the authentication boundary: authenticated delegation is unavailable to model-driven tools, and direct host-side setup and execution belong to the operator.
277
- - **`references/tmux-driving.md`** — full polling implementation, ANSI handling, session-died recovery, the `capture-pane` fallback details, the worktree-is-not-scratch distinction.
278
- - **`references/stop-hook.md`** — complete `Stop` event JSON schema, `SubagentStop` differences, transcript JSONL schema (unofficial but reverse-engineered), documented race conditions to handle.
279
- - **`typeclaw-config`** — the `docker.file.claudeCode` toggle that gates the install.
280
- - **`typeclaw-git`** — commit discipline for any cherry-picks or hand-copies from claude's worktree back into the agent folder.
281
- - **`typeclaw-monorepo`** — the `workspace/` vs `packages/` distinction (this skill uses `/tmp/`, not `workspace/`, for reasons explained above).
46
+ Only the trusted runtime handles provider credentials. The child receives an invocation-local capability, not a provider token. Never put credentials in chat, prompts, files, tool arguments, or child environment; never run login/setup-token, dump profiles, or use guard acknowledgements as an authentication workaround. Raw bash invocations of `claude` do not acquire broker authority. For Codex on the same tool, use the `typeclaw-codex-cli` skill.
@@ -1,29 +1,13 @@
1
- # Auth flow — operator-owned (Claude Code)
1
+ # Authentication through the runtime broker
2
2
 
3
- Claude Code authentication is outside the model-driven tool boundary. **Authenticated Claude Code delegation is unavailable from model-driven TypeClaw tools.** The agent must not read, print, parse, copy, write, verify, or probe any credential value or credential file.
3
+ The host operator configures `providers.anthropic` through `typeclaw provider add anthropic` and enables `docker.file.claudeCode`. Rebuild/restart on the host when the installed binary is missing. The runtime uses the canonical credential store and coordinates refresh with ordinary agent requests.
4
4
 
5
- ## No readiness bypass
5
+ The tool reports readiness failures safely. Missing credentials affect this task, not startup or other providers. A revoked subscription needs host re-login, not model-side token handling. API-key and subscription authentication remain distinct; the broker never silently falls back from a failed subscription to API billing.
6
6
 
7
- Do not check environment variables or profile-file existence as a way to enable delegation. TypeClaw masks canonical credential files and directories from model-driven bash, strips reusable credential environments, and unconditionally blocks non-bash tools from opening them. Provider authentication available to trusted runtime code is not delegated to a model-driven Claude child.
7
+ The sandboxed child has only a random, short-lived loopback capability. The broker accepts the selected model and explicit helper model on Messages/count-token routes, injects provider authentication upstream, and revokes the capability when the invocation ends. There is no token, refresh, login, or arbitrary proxy endpoint.
8
8
 
9
- ## When authentication is missing
9
+ Never inspect `.env`, `secrets.json`, `auth.json`, runtime HOME, or Claude profiles. Do not request `claude login`/`setup-token` output, copy credentials into a task, or send them through chat or tool arguments. Guard acknowledgements do not alter this boundary.
10
10
 
11
- Stop the delegation and tell the operator:
11
+ Ordinary operator-declared `.env` values can already be visible to model bash. The confidentiality guarantee covers private canonical credentials not also exposed there, in prompts, or source history. The delegated runner does not inherit ambient credential variables.
12
12
 
13
- > Authenticated Claude Code delegation is unavailable from model-driven TypeClaw tools. Authenticate and run Claude Code directly as the host-side operator. Do not send an API key or OAuth token in chat.
14
-
15
- The operator may manage Claude Code authentication directly on the host. The model must not broker that path, request `claude setup-token` output, or transfer a credential into the container.
16
-
17
- If Claude Code presents an auth prompt that requires entering or inspecting a credential, exit the delegated session. Do not run `claude setup-token` in the container or paste a key/token through tmux.
18
-
19
- ## Runtime separation
20
-
21
- Trusted runtime provisioning does not authorize a model-driven child. Any exported persistent profile remains masked, and the sandbox intentionally does not mount it or preserve Anthropic credential variables. Restarting cannot change this policy boundary.
22
-
23
- ## Hard prohibitions
24
-
25
- - Never ask for or accept an API key, OAuth token, access token, or credential-file contents in chat.
26
- - Never use `read`, `write`, `edit`, `look_at`, channel attachment tools, or shell commands to access `.env`, `secrets.json`, `auth.json`, `~/.claude/.credentials.json`, or their persistent backing directories.
27
- - Never put credentials in prompts, tmux keystrokes, command arguments, sentinels, transcripts, logs, commits, or scratch files.
28
- - Never treat a guard acknowledgement as authorization to handle credentials. Canonical credentials are blocked independently of plugin guard hooks.
29
- - If a credential is offered, tell the user not to send it and redirect them to host-side setup.
13
+ If auth fails, return the safe diagnostic to the parent and retain the worktree. Do not change endpoints or broaden the broker's routes to fix unsupported account/cloud features.
@@ -0,0 +1,11 @@
1
+ # Headless sessions
2
+
3
+ `coding_agent` invokes `claude -p --output-format stream-json --verbose` with a concrete model and the prompt on stdin. Print mode runs the agent loop, tools, and subagents. No TTY, tmux server, sleep loop, or Stop sentinel is needed.
4
+
5
+ The runtime waits for a terminal result **and process exit**, draining bounded stdout and stderr throughout. Intermediate results do not terminate the child. Malformed output, nonzero exit, missing terminal results, and permission denials produce failed or incomplete receipts, not invented success. The protocol works independently of the language in the final answer.
6
+
7
+ First turns use a new UUID; subsequent invocations resume the recorded emitted session with `--resume`. The same task keeps its private Git database, worktree, and Claude conversation directory. Never use `--continue` or select the latest session under concurrency.
8
+
9
+ Code mode pre-approves useful coding tools with `dontAsk`. Plan mode uses Claude plan permission mode **and** read-only sandbox mounts for the worktree/Git database. Native permission flags do not replace TypeClaw's outer sandbox. A denied operation needs a revised task or explicit authorized mode transition, not a TUI confirmation workaround.
10
+
11
+ Each invocation defaults to 1800 seconds. Cancellation or timeout kills and reaps the sandbox process group and closes its broker. Partial edits and session state remain available. A later run obtains a new capability; an old one never becomes valid again. If no resumable session was emitted, inspect the partial diff rather than silently replacing the conversation.
@@ -0,0 +1,13 @@
1
+ # Results and worktrees
2
+
3
+ Container task files live under `/agent/workspace/coding-agents/<task-id>/`: `git/`, `worktree/`, `claude/`, and `output/`. They survive container recreation through the agent bind mount and do not enter session/memory backups.
4
+
5
+ The source revision is committed HEAD. Every receipt warns that uncommitted source edits are excluded; dirty-input snapshots and authenticated submodule imports are not supported. Never auto-commit the source to prepare a task. Bootstrap reads only the source's Git metadata; the live source worktree and credential write directory are never mounted or inspected for dirty status. The task uses copied objects and an actual detached worktree in a private Git database.
6
+
7
+ The receipt records the task, source, base SHA, worktree, terminal state, final message, exit status, changed and untracked files, patch path, and safe diagnostic. `changes.patch` is binary-capable and covers staged/unstaged edits, untracked files, deletions, executable modes, and symlinks. `changes.json` records the inventory. Oversized artifacts are explicitly incomplete, not silently truncated.
8
+
9
+ Review the complete patch and relevant tests before applying through normal tools. A CLI saying "done" does not prove acceptance checks passed. The tool never commits, pushes, merges, opens a PR, or posts to a channel.
10
+
11
+ `result` reads runtime-owned authority; writable `output/result.json` is only an artifact. Task IDs do not authorize other speakers or sibling operators. After restart, formerly running tasks are interrupted and require explicit resume. Do not delete failure evidence automatically.
12
+
13
+ `dispose` requires `discard:true` and a stopped task. It removes only that task's worktree/private directory. Never run global `git worktree prune`, delete source branches, or glob other tasks.