@cursor/bdk 0.2.10 → 0.2.12

package/dist/docs/reference/hooks.html

@@ -6,54 +6,54 @@
     <title>Hooks | Grok Bot Development Kit (BDK)</title>
     <meta name="description" content="Observe-only subscribers to the session event stream: audit logs, metrics, transcript mirrors, derived state.">
     <meta name="generator" content="VitePress v1.6.4">
-    <link rel="preload stylesheet" href="/docs/assets/style.C130MVnH.css" as="style">
+    <link rel="preload stylesheet" href="/docs/assets/style.Dwls12uf.css" as="style">
     <link rel="preload stylesheet" href="/docs/vp-icons.css" as="style">
     
-    <script type="module" src="/docs/assets/app.DXI7bwox.js"></script>
+    <script type="module" src="/docs/assets/app.CKta5zX1.js"></script>
     <link rel="preload" href="/docs/assets/inter-roman-latin.Di8DUHzh.woff2" as="font" type="font/woff2" crossorigin="">
     <link rel="modulepreload" href="/docs/assets/chunks/framework.BNw1pucY.js">
-    <link rel="modulepreload" href="/docs/assets/chunks/theme.DaplWQhQ.js">
+    <link rel="modulepreload" href="/docs/assets/chunks/theme.BcgOnbZ6.js">
     <link rel="modulepreload" href="/docs/assets/chunks/katex.DkKDou_j.js">
-    <link rel="modulepreload" href="/docs/assets/chunks/dagre-KV5264BT.DS1L6hJt.js">
-    <link rel="modulepreload" href="/docs/assets/chunks/cose-bilkent-S5V4N54A.1SP8al9c.js">
-    <link rel="modulepreload" href="/docs/assets/chunks/c4Diagram-AHTNJAMY.B9HV5PFR.js">
-    <link rel="modulepreload" href="/docs/assets/chunks/flowDiagram-DWJPFMVM.CQgN4TTz.js">
-    <link rel="modulepreload" href="/docs/assets/chunks/erDiagram-SMLLAGMA.BSak5OSP.js">
-    <link rel="modulepreload" href="/docs/assets/chunks/gitGraphDiagram-UUTBAWPF.CdS7Ucll.js">
-    <link rel="modulepreload" href="/docs/assets/chunks/ganttDiagram-T4ZO3ILL.GrT0kA4a.js">
-    <link rel="modulepreload" href="/docs/assets/chunks/infoDiagram-42DDH7IO.C3C9FRto.js">
-    <link rel="modulepreload" href="/docs/assets/chunks/pieDiagram-DEJITSTG.Cz1WIv9r.js">
-    <link rel="modulepreload" href="/docs/assets/chunks/quadrantDiagram-34T5L4WZ.DKLFxcjy.js">
-    <link rel="modulepreload" href="/docs/assets/chunks/xychartDiagram-5P7HB3ND.CLPZEIU9.js">
-    <link rel="modulepreload" href="/docs/assets/chunks/requirementDiagram-MS252O5E.BHegiK7x.js">
-    <link rel="modulepreload" href="/docs/assets/chunks/sequenceDiagram-FGHM5R23.DYQ1QUrI.js">
-    <link rel="modulepreload" href="/docs/assets/chunks/classDiagram-6PBFFD2Q.CbC_mrvB.js">
-    <link rel="modulepreload" href="/docs/assets/chunks/classDiagram-v2-HSJHXN6E.CbC_mrvB.js">
-    <link rel="modulepreload" href="/docs/assets/chunks/stateDiagram-FHFEXIEX.Iru8BsFo.js">
-    <link rel="modulepreload" href="/docs/assets/chunks/stateDiagram-v2-QKLJ7IA2.BYXl4LW6.js">
-    <link rel="modulepreload" href="/docs/assets/chunks/journeyDiagram-VCZTEJTY.CaHMfK4b.js">
-    <link rel="modulepreload" href="/docs/assets/chunks/timeline-definition-GMOUNBTQ.BwFA8hiX.js">
-    <link rel="modulepreload" href="/docs/assets/chunks/mindmap-definition-QFDTVHPH.BVJ1Bbnk.js">
-    <link rel="modulepreload" href="/docs/assets/chunks/kanban-definition-6JOO6SKY.CjhIUwcA.js">
-    <link rel="modulepreload" href="/docs/assets/chunks/sankeyDiagram-XADWPNL6.DYkY6yPc.js">
-    <link rel="modulepreload" href="/docs/assets/chunks/diagram-TYMM5635.BVswXWrB.js">
-    <link rel="modulepreload" href="/docs/assets/chunks/diagram-MMDJMWI5.DPA9Dk_P.js">
-    <link rel="modulepreload" href="/docs/assets/chunks/blockDiagram-DXYQGD6D.BsRW6GoB.js">
-    <link rel="modulepreload" href="/docs/assets/chunks/diagram-5BDNPKRD.ChsausbG.js">
-    <link rel="modulepreload" href="/docs/assets/chunks/architectureDiagram-Q4EWVU46.C0hsMZnZ.js">
-    <link rel="modulepreload" href="/docs/assets/chunks/ishikawaDiagram-UXIWVN3A.2FuAh_Zj.js">
-    <link rel="modulepreload" href="/docs/assets/chunks/vennDiagram-DHZGUBPP.CZ60W1C_.js">
-    <link rel="modulepreload" href="/docs/assets/chunks/diagram-G4DWMVQ6.3XsptNWj.js">
-    <link rel="modulepreload" href="/docs/assets/chunks/wardleyDiagram-NUSXRM2D.B69D2r8-.js">
+    <link rel="modulepreload" href="/docs/assets/chunks/dagre-KV5264BT.PCD6KQDb.js">
+    <link rel="modulepreload" href="/docs/assets/chunks/cose-bilkent-S5V4N54A.CrfA7Iw_.js">
+    <link rel="modulepreload" href="/docs/assets/chunks/c4Diagram-AHTNJAMY.dnbRC3Dm.js">
+    <link rel="modulepreload" href="/docs/assets/chunks/flowDiagram-DWJPFMVM.8i7zsxuh.js">
+    <link rel="modulepreload" href="/docs/assets/chunks/erDiagram-SMLLAGMA.4gOY_C3v.js">
+    <link rel="modulepreload" href="/docs/assets/chunks/gitGraphDiagram-UUTBAWPF.ACzeLGiB.js">
+    <link rel="modulepreload" href="/docs/assets/chunks/ganttDiagram-T4ZO3ILL.BEKHYdM-.js">
+    <link rel="modulepreload" href="/docs/assets/chunks/infoDiagram-42DDH7IO.D8R9obOH.js">
+    <link rel="modulepreload" href="/docs/assets/chunks/pieDiagram-DEJITSTG.D_q4SVDT.js">
+    <link rel="modulepreload" href="/docs/assets/chunks/quadrantDiagram-34T5L4WZ.D3zGj5ok.js">
+    <link rel="modulepreload" href="/docs/assets/chunks/xychartDiagram-5P7HB3ND.Cw8-tJmw.js">
+    <link rel="modulepreload" href="/docs/assets/chunks/requirementDiagram-MS252O5E.DVTg7zr2.js">
+    <link rel="modulepreload" href="/docs/assets/chunks/sequenceDiagram-FGHM5R23.Dpjai9YP.js">
+    <link rel="modulepreload" href="/docs/assets/chunks/classDiagram-6PBFFD2Q.DFNHq2OM.js">
+    <link rel="modulepreload" href="/docs/assets/chunks/classDiagram-v2-HSJHXN6E.DFNHq2OM.js">
+    <link rel="modulepreload" href="/docs/assets/chunks/stateDiagram-FHFEXIEX.D_AbQBuP.js">
+    <link rel="modulepreload" href="/docs/assets/chunks/stateDiagram-v2-QKLJ7IA2.CWKWRxRx.js">
+    <link rel="modulepreload" href="/docs/assets/chunks/journeyDiagram-VCZTEJTY.DUzjGfoZ.js">
+    <link rel="modulepreload" href="/docs/assets/chunks/timeline-definition-GMOUNBTQ.Cp3DKBe2.js">
+    <link rel="modulepreload" href="/docs/assets/chunks/mindmap-definition-QFDTVHPH.Ggu0jg86.js">
+    <link rel="modulepreload" href="/docs/assets/chunks/kanban-definition-6JOO6SKY.DbcW2iZ0.js">
+    <link rel="modulepreload" href="/docs/assets/chunks/sankeyDiagram-XADWPNL6.D3X8jm57.js">
+    <link rel="modulepreload" href="/docs/assets/chunks/diagram-TYMM5635.DDGqH_4B.js">
+    <link rel="modulepreload" href="/docs/assets/chunks/diagram-MMDJMWI5.DHlkZHNV.js">
+    <link rel="modulepreload" href="/docs/assets/chunks/blockDiagram-DXYQGD6D.dAc4goE-.js">
+    <link rel="modulepreload" href="/docs/assets/chunks/diagram-5BDNPKRD.CGNlYlP1.js">
+    <link rel="modulepreload" href="/docs/assets/chunks/architectureDiagram-Q4EWVU46.Mt2UV5M-.js">
+    <link rel="modulepreload" href="/docs/assets/chunks/ishikawaDiagram-UXIWVN3A.CmgYpCWL.js">
+    <link rel="modulepreload" href="/docs/assets/chunks/vennDiagram-DHZGUBPP.Bcvg-Aqu.js">
+    <link rel="modulepreload" href="/docs/assets/chunks/diagram-G4DWMVQ6.C0cvryPD.js">
+    <link rel="modulepreload" href="/docs/assets/chunks/wardleyDiagram-NUSXRM2D.L0yehCc5.js">
     <link rel="modulepreload" href="/docs/assets/chunks/virtual_mermaid-config.DDnGl6nM.js">
-    <link rel="modulepreload" href="/docs/assets/reference_hooks.md.C5LCJ1R3.lean.js">
+    <link rel="modulepreload" href="/docs/assets/reference_hooks.md.B-eGa2km.lean.js">
     <script id="check-dark-mode">(()=>{const e=localStorage.getItem("vitepress-theme-appearance")||"auto",a=window.matchMedia("(prefers-color-scheme: dark)").matches;(!e||e==="auto"?a:e==="dark")&&document.documentElement.classList.add("dark")})();</script>
     <script id="check-mac-os">document.documentElement.classList.toggle("mac",/Mac|iPhone|iPod|iPad/i.test(navigator.platform));</script>
     <link rel="alternate" type="text/plain" href="/docs/llms.txt">
     <link rel="alternate" type="text/markdown" href="/docs/reference/hooks.md">
   </head>
   <body>
-    <div id="app"><div class="Layout" data-v-76086e96><!--[--><!--]--><!--[--><span tabindex="-1" data-v-97fb5898></span><a href="#VPContent" class="VPSkipLink visually-hidden" data-v-97fb5898>Skip to content</a><!--]--><!----><header class="VPNav" data-v-76086e96 data-v-781b1279><div class="VPNavBar" data-v-781b1279 data-v-b33015df><div class="wrapper" data-v-b33015df><div class="container" data-v-b33015df><div class="title" data-v-b33015df><div class="VPNavBarTitle has-sidebar" data-v-b33015df data-v-a0c466dc><a class="title" href="/docs/" data-v-a0c466dc><!--[--><!--]--><!----><span data-v-a0c466dc>Grok Bot Development Kit (BDK)</span><!--[--><!--[--><!--[--><!--[--><span class="bdk-version" title="BDK 0.2.10 (@cursor/bdk package)" data-v-d89e5038>0.2.10</span><!--]--><!--]--><!--]--><!--]--></a></div></div><div class="content" data-v-b33015df><div class="content-body" data-v-b33015df><!--[--><!--]--><div class="VPNavBarSearch search" data-v-b33015df><!--[--><!----><div id="local-search"><button type="button" class="DocSearch DocSearch-Button" aria-label="Search"><span class="DocSearch-Button-Container"><span class="vp-icon DocSearch-Search-Icon"></span><span class="DocSearch-Button-Placeholder">Search</span></span><span class="DocSearch-Button-Keys"><kbd class="DocSearch-Button-Key"></kbd><kbd class="DocSearch-Button-Key">K</kbd></span></button></div><!--]--></div><nav aria-labelledby="main-nav-aria-label" class="VPNavBarMenu menu" data-v-b33015df data-v-8906c751><span id="main-nav-aria-label" class="visually-hidden" data-v-8906c751> Main Navigation </span><!--[--><!--[--><a class="VPLink link VPNavBarMenuLink" href="/docs/quickstart.html" tabindex="0" data-v-8906c751 data-v-e9bcc08e><!--[--><span data-v-e9bcc08e>Quickstart</span><!--]--></a><!--]--><!--[--><a class="VPLink link VPNavBarMenuLink" href="/docs/guides/mcp-oauth.html" tabindex="0" data-v-8906c751 data-v-e9bcc08e><!--[--><span data-v-e9bcc08e>Guides</span><!--]--></a><!--]--><!--[--><a class="VPLink link VPNavBarMenuLink" href="/docs/guides/github.html" tabindex="0" data-v-8906c751 data-v-e9bcc08e><!--[--><span data-v-e9bcc08e>Integrations</span><!--]--></a><!--]--><!--[--><a class="VPLink link VPNavBarMenuLink" href="/docs/templates/security-reviewer.html" tabindex="0" data-v-8906c751 data-v-e9bcc08e><!--[--><span data-v-e9bcc08e>Templates</span><!--]--></a><!--]--><!--[--><a class="VPLink link VPNavBarMenuLink" href="/docs/reference/project-layout.html" tabindex="0" data-v-8906c751 data-v-e9bcc08e><!--[--><span data-v-e9bcc08e>Reference</span><!--]--></a><!--]--><!--]--></nav><!----><div class="VPNavBarAppearance appearance" data-v-b33015df data-v-959ed110><button class="VPSwitch VPSwitchAppearance" type="button" role="switch" title aria-checked="false" data-v-959ed110 data-v-79ad6d7f data-v-0a895de9><span class="check" data-v-0a895de9><span class="icon" data-v-0a895de9><!--[--><span class="vpi-sun sun" data-v-79ad6d7f></span><span class="vpi-moon moon" data-v-79ad6d7f></span><!--]--></span></span></button></div><!----><div class="VPFlyout VPNavBarExtra extra" data-v-b33015df data-v-a713f501 data-v-1d7aa189><button type="button" class="button" aria-haspopup="true" aria-expanded="false" aria-label="extra navigation" data-v-1d7aa189><span class="vpi-more-horizontal icon" data-v-1d7aa189></span></button><div class="menu" data-v-1d7aa189><div class="VPMenu" data-v-1d7aa189 data-v-e34b7e14><!----><!--[--><!--[--><!----><div class="group" data-v-a713f501><div class="item appearance" data-v-a713f501><p class="label" data-v-a713f501>Appearance</p><div class="appearance-action" data-v-a713f501><button class="VPSwitch VPSwitchAppearance" type="button" role="switch" title aria-checked="false" data-v-a713f501 data-v-79ad6d7f data-v-0a895de9><span class="check" data-v-0a895de9><span class="icon" data-v-0a895de9><!--[--><span class="vpi-sun sun" data-v-79ad6d7f></span><span class="vpi-moon moon" data-v-79ad6d7f></span><!--]--></span></span></button></div></div></div><!----><!--]--><!--]--></div></div></div><!--[--><!--]--><button type="button" class="VPNavBarHamburger hamburger" aria-label="mobile navigation" aria-expanded="false" aria-controls="VPNavScreen" data-v-b33015df data-v-cb5d0edb><span class="container" data-v-cb5d0edb><span class="top" data-v-cb5d0edb></span><span class="middle" data-v-cb5d0edb></span><span class="bottom" data-v-cb5d0edb></span></span></button></div></div></div></div><div class="divider" data-v-b33015df><div class="divider-line" data-v-b33015df></div></div></div><!----></header><div class="VPLocalNav has-sidebar empty" data-v-76086e96 data-v-6f794310><div class="container" data-v-6f794310><button class="menu" aria-expanded="false" aria-controls="VPSidebarNav" data-v-6f794310><span class="vpi-align-left menu-icon" data-v-6f794310></span><span class="menu-text" data-v-6f794310>Menu</span></button><div class="VPLocalNavOutlineDropdown" style="--vp-vh:0px;" data-v-6f794310 data-v-bab84d9c><button data-v-bab84d9c>Return to top</button><!----></div></div></div><aside class="VPSidebar" data-v-76086e96 data-v-4daa293d><div class="curtain" data-v-4daa293d></div><nav class="nav" id="VPSidebarNav" aria-labelledby="sidebar-aria-label" tabindex="-1" data-v-4daa293d><span class="visually-hidden" id="sidebar-aria-label" data-v-4daa293d> Sidebar Navigation </span><!--[--><!--]--><!--[--><div class="no-transition group" data-v-095feacd><section class="VPSidebarItem level-0" data-v-095feacd data-v-d79cbf7e><div class="item" role="button" tabindex="0" data-v-d79cbf7e><div class="indicator" data-v-d79cbf7e></div><h2 class="text" data-v-d79cbf7e>Getting started</h2><!----></div><div class="items" data-v-d79cbf7e><!--[--><div class="VPSidebarItem level-1 is-link" data-v-d79cbf7e><div class="item" data-v-d79cbf7e><div class="indicator" data-v-d79cbf7e></div><a class="VPLink link link" href="/docs/" data-v-d79cbf7e><!--[--><p class="text" data-v-d79cbf7e>Overview</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-d79cbf7e><div class="item" data-v-d79cbf7e><div class="indicator" data-v-d79cbf7e></div><a class="VPLink link link" href="/docs/quickstart.html" data-v-d79cbf7e><!--[--><p class="text" data-v-d79cbf7e>Building your first agent</p><!--]--></a><!----></div><!----></div><!--]--></div></section></div><div class="no-transition group" data-v-095feacd><section class="VPSidebarItem level-0 collapsible" data-v-095feacd data-v-d79cbf7e><div class="item" role="button" tabindex="0" data-v-d79cbf7e><div class="indicator" data-v-d79cbf7e></div><h2 class="text" data-v-d79cbf7e>Integrations</h2><div class="caret" role="button" aria-label="toggle section" tabindex="0" data-v-d79cbf7e><span class="vpi-chevron-right caret-icon" data-v-d79cbf7e></span></div></div><div class="items" data-v-d79cbf7e><!--[--><div class="VPSidebarItem level-1 is-link" data-v-d79cbf7e><div class="item" data-v-d79cbf7e><div class="indicator" data-v-d79cbf7e></div><a class="VPLink link link" href="/docs/guides/github.html" data-v-d79cbf7e><!--[--><p class="text" data-v-d79cbf7e>GitHub</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-d79cbf7e><div class="item" data-v-d79cbf7e><div class="indicator" data-v-d79cbf7e></div><a class="VPLink link link" href="/docs/guides/slack.html" data-v-d79cbf7e><!--[--><p class="text" data-v-d79cbf7e>Slack</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-d79cbf7e><div class="item" data-v-d79cbf7e><div class="indicator" data-v-d79cbf7e></div><a class="VPLink link link" href="/docs/guides/webhooks.html" data-v-d79cbf7e><!--[--><p class="text" data-v-d79cbf7e>Webhooks</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-d79cbf7e><div class="item" data-v-d79cbf7e><div class="indicator" data-v-d79cbf7e></div><a class="VPLink link link" href="/docs/guides/convert-automation.html" data-v-d79cbf7e><!--[--><p class="text" data-v-d79cbf7e>Cursor Automations</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-d79cbf7e><div class="item" data-v-d79cbf7e><div class="indicator" data-v-d79cbf7e></div><a class="VPLink link link" href="/docs/guides/opentelemetry.html" data-v-d79cbf7e><!--[--><p class="text" data-v-d79cbf7e>OpenTelemetry</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-d79cbf7e><div class="item" data-v-d79cbf7e><div class="indicator" data-v-d79cbf7e></div><a class="VPLink link link" href="/docs/guides/gitlab.html" data-v-d79cbf7e><!--[--><p class="text" data-v-d79cbf7e>GitLab</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-d79cbf7e><div class="item" data-v-d79cbf7e><div class="indicator" data-v-d79cbf7e></div><a class="VPLink link link" href="/docs/guides/bitbucket.html" data-v-d79cbf7e><!--[--><p class="text" data-v-d79cbf7e>Bitbucket</p><!--]--></a><!----></div><!----></div><!--]--></div></section></div><div class="no-transition group" data-v-095feacd><section class="VPSidebarItem level-0 collapsible" data-v-095feacd data-v-d79cbf7e><div class="item" role="button" tabindex="0" data-v-d79cbf7e><div class="indicator" data-v-d79cbf7e></div><h2 class="text" data-v-d79cbf7e>Extensions</h2><div class="caret" role="button" aria-label="toggle section" tabindex="0" data-v-d79cbf7e><span class="vpi-chevron-right caret-icon" data-v-d79cbf7e></span></div></div><div class="items" data-v-d79cbf7e><!--[--><div class="VPSidebarItem level-1 is-link" data-v-d79cbf7e><div class="item" data-v-d79cbf7e><div class="indicator" data-v-d79cbf7e></div><a class="VPLink link link" href="/docs/reference/extensions.html" data-v-d79cbf7e><!--[--><p class="text" data-v-d79cbf7e>Overview</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-d79cbf7e><div class="item" data-v-d79cbf7e><div class="indicator" data-v-d79cbf7e></div><a class="VPLink link link" href="/docs/guides/cloud-agents.html" data-v-d79cbf7e><!--[--><p class="text" data-v-d79cbf7e>Cloud agents</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-d79cbf7e><div class="item" data-v-d79cbf7e><div class="indicator" data-v-d79cbf7e></div><a class="VPLink link link" href="/docs/guides/grokbot-agents.html" data-v-d79cbf7e><!--[--><p class="text" data-v-d79cbf7e>Grok Bot agents</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-d79cbf7e><div class="item" data-v-d79cbf7e><div class="indicator" data-v-d79cbf7e></div><a class="VPLink link link" href="/docs/guides/improve.html" data-v-d79cbf7e><!--[--><p class="text" data-v-d79cbf7e>Self-improvement</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-d79cbf7e><div class="item" data-v-d79cbf7e><div class="indicator" data-v-d79cbf7e></div><a class="VPLink link link" href="/docs/guides/jev.html" data-v-d79cbf7e><!--[--><p class="text" data-v-d79cbf7e>Jev</p><!--]--></a><!----></div><!----></div><!--]--></div></section></div><div class="no-transition group" data-v-095feacd><section class="VPSidebarItem level-0 collapsible" data-v-095feacd data-v-d79cbf7e><div class="item" role="button" tabindex="0" data-v-d79cbf7e><div class="indicator" data-v-d79cbf7e></div><h2 class="text" data-v-d79cbf7e>Guides</h2><div class="caret" role="button" aria-label="toggle section" tabindex="0" data-v-d79cbf7e><span class="vpi-chevron-right caret-icon" data-v-d79cbf7e></span></div></div><div class="items" data-v-d79cbf7e><!--[--><div class="VPSidebarItem level-1 is-link" data-v-d79cbf7e><div class="item" data-v-d79cbf7e><div class="indicator" data-v-d79cbf7e></div><a class="VPLink link link" href="/docs/guides/mcp-oauth.html" data-v-d79cbf7e><!--[--><p class="text" data-v-d79cbf7e>MCP</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-d79cbf7e><div class="item" data-v-d79cbf7e><div class="indicator" data-v-d79cbf7e></div><a class="VPLink link link" href="/docs/guides/hooks.html" data-v-d79cbf7e><!--[--><p class="text" data-v-d79cbf7e>Hooks</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-d79cbf7e><div class="item" data-v-d79cbf7e><div class="indicator" data-v-d79cbf7e></div><a class="VPLink link link" href="/docs/guides/agent-to-agent.html" data-v-d79cbf7e><!--[--><p class="text" data-v-d79cbf7e>Peer agents</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-d79cbf7e><div class="item" data-v-d79cbf7e><div class="indicator" data-v-d79cbf7e></div><a class="VPLink link link" href="/docs/deployment.html" data-v-d79cbf7e><!--[--><p class="text" data-v-d79cbf7e>Deployment</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-d79cbf7e><div class="item" data-v-d79cbf7e><div class="indicator" data-v-d79cbf7e></div><a class="VPLink link link" href="/docs/guides/migrate.html" data-v-d79cbf7e><!--[--><p class="text" data-v-d79cbf7e>Early-alpha migration</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-d79cbf7e><div class="item" data-v-d79cbf7e><div class="indicator" data-v-d79cbf7e></div><a class="VPLink link link" href="/docs/evals.html" data-v-d79cbf7e><!--[--><p class="text" data-v-d79cbf7e>Evals</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-d79cbf7e><div class="item" data-v-d79cbf7e><div class="indicator" data-v-d79cbf7e></div><a class="VPLink link link" href="/docs/hillclimbing.html" data-v-d79cbf7e><!--[--><p class="text" data-v-d79cbf7e>Hillclimbing</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-d79cbf7e><div class="item" data-v-d79cbf7e><div class="indicator" data-v-d79cbf7e></div><a class="VPLink link link" href="/docs/building-with-agents.html" data-v-d79cbf7e><!--[--><p class="text" data-v-d79cbf7e>Build with a coding agent</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-d79cbf7e><div class="item" data-v-d79cbf7e><div class="indicator" data-v-d79cbf7e></div><a class="VPLink link link" href="/docs/troubleshooting.html" data-v-d79cbf7e><!--[--><p class="text" data-v-d79cbf7e>Troubleshooting</p><!--]--></a><!----></div><!----></div><!--]--></div></section></div><div class="no-transition group" data-v-095feacd><section class="VPSidebarItem level-0 collapsible" data-v-095feacd data-v-d79cbf7e><div class="item" role="button" tabindex="0" data-v-d79cbf7e><div class="indicator" data-v-d79cbf7e></div><h2 class="text" data-v-d79cbf7e>Templates</h2><div class="caret" role="button" aria-label="toggle section" tabindex="0" data-v-d79cbf7e><span class="vpi-chevron-right caret-icon" data-v-d79cbf7e></span></div></div><div class="items" data-v-d79cbf7e><!--[--><div class="VPSidebarItem level-1 is-link" data-v-d79cbf7e><div class="item" data-v-d79cbf7e><div class="indicator" data-v-d79cbf7e></div><a class="VPLink link link" href="/docs/templates/grokbot-agents.html" data-v-d79cbf7e><!--[--><p class="text" data-v-d79cbf7e>Grok Bot agents</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-d79cbf7e><div class="item" data-v-d79cbf7e><div class="indicator" data-v-d79cbf7e></div><a class="VPLink link link" href="/docs/templates/security-reviewer.html" data-v-d79cbf7e><!--[--><p class="text" data-v-d79cbf7e>Security reviewer</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-d79cbf7e><div class="item" data-v-d79cbf7e><div class="indicator" data-v-d79cbf7e></div><a class="VPLink link link" href="/docs/templates/thermo-review.html" data-v-d79cbf7e><!--[--><p class="text" data-v-d79cbf7e>Thermo review</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-d79cbf7e><div class="item" data-v-d79cbf7e><div class="indicator" data-v-d79cbf7e></div><a class="VPLink link link" href="/docs/templates/thermo-quality-review.html" data-v-d79cbf7e><!--[--><p class="text" data-v-d79cbf7e>Thermo quality review</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-d79cbf7e><div class="item" data-v-d79cbf7e><div class="indicator" data-v-d79cbf7e></div><a class="VPLink link link" href="/docs/templates/agentic-owners.html" data-v-d79cbf7e><!--[--><p class="text" data-v-d79cbf7e>Agentic Approver</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-d79cbf7e><div class="item" data-v-d79cbf7e><div class="indicator" data-v-d79cbf7e></div><a class="VPLink link link" href="/docs/templates/triage.html" data-v-d79cbf7e><!--[--><p class="text" data-v-d79cbf7e>Triage agent</p><!--]--></a><!----></div><!----></div><!--]--></div></section></div><div class="no-transition group" data-v-095feacd><section class="VPSidebarItem level-0 collapsible has-active" data-v-095feacd data-v-d79cbf7e><div class="item" role="button" tabindex="0" data-v-d79cbf7e><div class="indicator" data-v-d79cbf7e></div><h2 class="text" data-v-d79cbf7e>Reference</h2><div class="caret" role="button" aria-label="toggle section" tabindex="0" data-v-d79cbf7e><span class="vpi-chevron-right caret-icon" data-v-d79cbf7e></span></div></div><div class="items" data-v-d79cbf7e><!--[--><div class="VPSidebarItem level-1 is-link" data-v-d79cbf7e><div class="item" data-v-d79cbf7e><div class="indicator" data-v-d79cbf7e></div><a class="VPLink link link" href="/docs/reference/project-layout.html" data-v-d79cbf7e><!--[--><p class="text" data-v-d79cbf7e>Project layout</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-d79cbf7e><div class="item" data-v-d79cbf7e><div class="indicator" data-v-d79cbf7e></div><a class="VPLink link link" href="/docs/reference/agent-config.html" data-v-d79cbf7e><!--[--><p class="text" data-v-d79cbf7e>Agent config</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-d79cbf7e><div class="item" data-v-d79cbf7e><div class="indicator" data-v-d79cbf7e></div><a class="VPLink link link" href="/docs/reference/instructions.html" data-v-d79cbf7e><!--[--><p class="text" data-v-d79cbf7e>Instructions</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-d79cbf7e><div class="item" data-v-d79cbf7e><div class="indicator" data-v-d79cbf7e></div><a class="VPLink link link" href="/docs/reference/tools.html" data-v-d79cbf7e><!--[--><p class="text" data-v-d79cbf7e>Tools</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-d79cbf7e><div class="item" data-v-d79cbf7e><div class="indicator" data-v-d79cbf7e></div><a class="VPLink link link" href="/docs/reference/prompt.html" data-v-d79cbf7e><!--[--><p class="text" data-v-d79cbf7e>prompt</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-d79cbf7e><div class="item" data-v-d79cbf7e><div class="indicator" data-v-d79cbf7e></div><a class="VPLink link link" href="/docs/reference/skills.html" data-v-d79cbf7e><!--[--><p class="text" data-v-d79cbf7e>Skills</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-d79cbf7e><div class="item" data-v-d79cbf7e><div class="indicator" data-v-d79cbf7e></div><a class="VPLink link link" href="/docs/reference/connections.html" data-v-d79cbf7e><!--[--><p class="text" data-v-d79cbf7e>MCP Connections</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-d79cbf7e><div class="item" data-v-d79cbf7e><div class="indicator" data-v-d79cbf7e></div><a class="VPLink link link" href="/docs/reference/subagents.html" data-v-d79cbf7e><!--[--><p class="text" data-v-d79cbf7e>Subagents</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-d79cbf7e><div class="item" data-v-d79cbf7e><div class="indicator" data-v-d79cbf7e></div><a class="VPLink link link" href="/docs/reference/channels.html" data-v-d79cbf7e><!--[--><p class="text" data-v-d79cbf7e>Channels</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-d79cbf7e><div class="item" data-v-d79cbf7e><div class="indicator" data-v-d79cbf7e></div><a class="VPLink link link" href="/docs/reference/schedules.html" data-v-d79cbf7e><!--[--><p class="text" data-v-d79cbf7e>Schedules & reminders</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-d79cbf7e><div class="item" data-v-d79cbf7e><div class="indicator" data-v-d79cbf7e></div><a class="VPLink link link" href="/docs/reference/hooks.html" data-v-d79cbf7e><!--[--><p class="text" data-v-d79cbf7e>Hooks</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-d79cbf7e><div class="item" data-v-d79cbf7e><div class="indicator" data-v-d79cbf7e></div><a class="VPLink link link" href="/docs/reference/evals.html" data-v-d79cbf7e><!--[--><p class="text" data-v-d79cbf7e>Evals</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-d79cbf7e><div class="item" data-v-d79cbf7e><div class="indicator" data-v-d79cbf7e></div><a class="VPLink link link" href="/docs/reference/artifacts.html" data-v-d79cbf7e><!--[--><p class="text" data-v-d79cbf7e>Artifacts</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-d79cbf7e><div class="item" data-v-d79cbf7e><div class="indicator" data-v-d79cbf7e></div><a class="VPLink link link" href="/docs/reference/sessions.html" data-v-d79cbf7e><!--[--><p class="text" data-v-d79cbf7e>Sessions & streaming</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-d79cbf7e><div class="item" data-v-d79cbf7e><div class="indicator" data-v-d79cbf7e></div><a class="VPLink link link" href="/docs/reference/playground.html" data-v-d79cbf7e><!--[--><p class="text" data-v-d79cbf7e>Playground</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-d79cbf7e><div class="item" data-v-d79cbf7e><div class="indicator" data-v-d79cbf7e></div><a class="VPLink link link" href="/docs/reference/cli.html" data-v-d79cbf7e><!--[--><p class="text" data-v-d79cbf7e>CLI</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-d79cbf7e><div class="item" data-v-d79cbf7e><div class="indicator" data-v-d79cbf7e></div><a class="VPLink link link" href="/docs/reference/http-api.html" data-v-d79cbf7e><!--[--><p class="text" data-v-d79cbf7e>HTTP API</p><!--]--></a><!----></div><!----></div><!--]--></div></section></div><!--]--><!--[--><!--]--></nav></aside><div class="VPContent has-sidebar" id="VPContent" data-v-76086e96 data-v-258cbba4><div class="VPDoc has-sidebar has-aside" data-v-258cbba4 data-v-afe580da><!--[--><!--]--><div class="container" data-v-afe580da><div class="aside" data-v-afe580da><div class="aside-curtain" data-v-afe580da></div><div class="aside-container" data-v-afe580da><div class="aside-content" data-v-afe580da><div class="VPDocAside" data-v-afe580da data-v-fb5275a4><!--[--><!--]--><!--[--><!--]--><nav aria-labelledby="doc-outline-aria-label" class="VPDocAsideOutline" data-v-fb5275a4 data-v-b3783f18><div class="content" data-v-b3783f18><div class="outline-marker" data-v-b3783f18></div><div aria-level="2" class="outline-title" id="doc-outline-aria-label" role="heading" data-v-b3783f18>On this page</div><ul class="VPDocOutlineItem root" data-v-b3783f18 data-v-72702c6e><!--[--><!--]--></ul></div></nav><!--[--><!--]--><div class="spacer" data-v-fb5275a4></div><!--[--><!--]--><!----><!--[--><!--]--><!--[--><!--]--></div></div></div></div><div class="content" data-v-afe580da><div class="content-container" data-v-afe580da><!--[--><!--]--><main class="main" data-v-afe580da><div style="position:relative;" class="vp-doc _docs_reference_hooks" data-v-afe580da><div><h1 id="hooks" tabindex="-1">Hooks <a class="header-anchor" href="#hooks" aria-label="Permalink to &quot;Hooks&quot;">​</a></h1><p>A hook subscribes to selected session events and can run a side effect after each matching event is recorded: an audit line, a metric, a transcript copy, or derived state. Hooks run in the serving process for every session of the agent. They cannot change the turn, the prompt, or the reply; a handler that throws is logged and skipped.</p><p>Treat the event as read-only. Later subscribers see the same object. That makes hooks safe to add to a production agent, and the wrong surface for anything that must run before the model or must fail a turn; see <a href="#hook-boundaries">Hook boundaries</a>.</p><p><code>defineHook</code> is unrelated to <a href="https://cursor.com/docs/agent/hooks" target="_blank" rel="noreferrer">Cursor Agent hooks</a>, the <code>.cursor/hooks.json</code> scripts that can observe, block, or modify the agent loop. Those still run inside a local session workspace.</p><h2 id="author-a-hook" tabindex="-1">Author a hook <a class="header-anchor" href="#author-a-hook" aria-label="Permalink to &quot;Author a hook&quot;">​</a></h2><p>Author <code>bot/hooks/&lt;name&gt;.ts</code> with <code>defineHook</code> from <code>@cursor/bdk/hooks</code>. This one meters tokens:</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// bot/hooks/usage.ts</span></span>
+    <div id="app"><div class="Layout" data-v-5ebc75e4><!--[--><!--]--><!--[--><span tabindex="-1" data-v-7de63af3></span><a href="#VPContent" class="VPSkipLink visually-hidden" data-v-7de63af3>Skip to content</a><!--]--><!----><header class="VPNav" data-v-5ebc75e4 data-v-e8579816><div class="VPNavBar" data-v-e8579816 data-v-bbf4446f><div class="wrapper" data-v-bbf4446f><div class="container" data-v-bbf4446f><div class="title" data-v-bbf4446f><div class="VPNavBarTitle has-sidebar" data-v-bbf4446f data-v-ebd5f04e><a class="title" href="/docs/" data-v-ebd5f04e><!--[--><!--]--><!----><span data-v-ebd5f04e>Grok Bot Development Kit (BDK)</span><!--[--><!--[--><!--[--><!--[--><span class="bdk-version" title="BDK 0.2.12 (@cursor/bdk package)" data-v-d89e5038>0.2.12</span><!--]--><!--]--><!--]--><!--]--></a></div></div><div class="content" data-v-bbf4446f><div class="content-body" data-v-bbf4446f><!--[--><!--]--><div class="VPNavBarSearch search" data-v-bbf4446f><!--[--><!----><div id="local-search"><button type="button" class="DocSearch DocSearch-Button" aria-label="Search"><span class="DocSearch-Button-Container"><span class="vp-icon DocSearch-Search-Icon"></span><span class="DocSearch-Button-Placeholder">Search</span></span><span class="DocSearch-Button-Keys"><kbd class="DocSearch-Button-Key"></kbd><kbd class="DocSearch-Button-Key">K</kbd></span></button></div><!--]--></div><nav aria-labelledby="main-nav-aria-label" class="VPNavBarMenu menu" data-v-bbf4446f data-v-7fa90d1c><span id="main-nav-aria-label" class="visually-hidden" data-v-7fa90d1c> Main Navigation </span><!--[--><!--[--><a class="VPLink link VPNavBarMenuLink" href="/docs/quickstart.html" tabindex="0" data-v-7fa90d1c data-v-8d7ed182><!--[--><span data-v-8d7ed182>Quickstart</span><!--]--></a><!--]--><!--[--><a class="VPLink link VPNavBarMenuLink" href="/docs/guides/mcp-oauth.html" tabindex="0" data-v-7fa90d1c data-v-8d7ed182><!--[--><span data-v-8d7ed182>Guides</span><!--]--></a><!--]--><!--[--><a class="VPLink link VPNavBarMenuLink" href="/docs/guides/github.html" tabindex="0" data-v-7fa90d1c data-v-8d7ed182><!--[--><span data-v-8d7ed182>Integrations</span><!--]--></a><!--]--><!--[--><a class="VPLink link VPNavBarMenuLink" href="/docs/templates/security-reviewer.html" tabindex="0" data-v-7fa90d1c data-v-8d7ed182><!--[--><span data-v-8d7ed182>Templates</span><!--]--></a><!--]--><!--[--><a class="VPLink link VPNavBarMenuLink" href="/docs/reference/project-layout.html" tabindex="0" data-v-7fa90d1c data-v-8d7ed182><!--[--><span data-v-8d7ed182>Reference</span><!--]--></a><!--]--><!--]--></nav><!----><div class="VPNavBarAppearance appearance" data-v-bbf4446f data-v-6a44a4fa><button class="VPSwitch VPSwitchAppearance" type="button" role="switch" title aria-checked="false" data-v-6a44a4fa data-v-b541f24b data-v-a48af969><span class="check" data-v-a48af969><span class="icon" data-v-a48af969><!--[--><span class="vpi-sun sun" data-v-b541f24b></span><span class="vpi-moon moon" data-v-b541f24b></span><!--]--></span></span></button></div><!----><div class="VPFlyout VPNavBarExtra extra" data-v-bbf4446f data-v-8d21ceac data-v-269c0ea1><button type="button" class="button" aria-haspopup="true" aria-expanded="false" aria-label="extra navigation" data-v-269c0ea1><span class="vpi-more-horizontal icon" data-v-269c0ea1></span></button><div class="menu" data-v-269c0ea1><div class="VPMenu" data-v-269c0ea1 data-v-ab92b832><!----><!--[--><!--[--><!----><div class="group" data-v-8d21ceac><div class="item appearance" data-v-8d21ceac><p class="label" data-v-8d21ceac>Appearance</p><div class="appearance-action" data-v-8d21ceac><button class="VPSwitch VPSwitchAppearance" type="button" role="switch" title aria-checked="false" data-v-8d21ceac data-v-b541f24b data-v-a48af969><span class="check" data-v-a48af969><span class="icon" data-v-a48af969><!--[--><span class="vpi-sun sun" data-v-b541f24b></span><span class="vpi-moon moon" data-v-b541f24b></span><!--]--></span></span></button></div></div></div><!----><!--]--><!--]--></div></div></div><!--[--><!--]--><button type="button" class="VPNavBarHamburger hamburger" aria-label="mobile navigation" aria-expanded="false" aria-controls="VPNavScreen" data-v-bbf4446f data-v-efff335d><span class="container" data-v-efff335d><span class="top" data-v-efff335d></span><span class="middle" data-v-efff335d></span><span class="bottom" data-v-efff335d></span></span></button></div></div></div></div><div class="divider" data-v-bbf4446f><div class="divider-line" data-v-bbf4446f></div></div></div><!----></header><div class="VPLocalNav has-sidebar empty" data-v-5ebc75e4 data-v-636a9279><div class="container" data-v-636a9279><button class="menu" aria-expanded="false" aria-controls="VPSidebarNav" data-v-636a9279><span class="vpi-align-left menu-icon" data-v-636a9279></span><span class="menu-text" data-v-636a9279>Menu</span></button><div class="VPLocalNavOutlineDropdown" style="--vp-vh:0px;" data-v-636a9279 data-v-ae38d8b4><button data-v-ae38d8b4>Return to top</button><!----></div></div></div><aside class="VPSidebar" data-v-5ebc75e4 data-v-f102723c><div class="curtain" data-v-f102723c></div><nav class="nav" id="VPSidebarNav" aria-labelledby="sidebar-aria-label" tabindex="-1" data-v-f102723c><span class="visually-hidden" id="sidebar-aria-label" data-v-f102723c> Sidebar Navigation </span><!--[--><!--]--><!--[--><div class="no-transition group" data-v-9c447dd5><section class="VPSidebarItem level-0" data-v-9c447dd5 data-v-8ccd545c><div class="item" role="button" tabindex="0" data-v-8ccd545c><div class="indicator" data-v-8ccd545c></div><h2 class="text" data-v-8ccd545c>Getting started</h2><!----></div><div class="items" data-v-8ccd545c><!--[--><div class="VPSidebarItem level-1 is-link" data-v-8ccd545c><div class="item" data-v-8ccd545c><div class="indicator" data-v-8ccd545c></div><a class="VPLink link link" href="/docs/" data-v-8ccd545c><!--[--><p class="text" data-v-8ccd545c>Overview</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-8ccd545c><div class="item" data-v-8ccd545c><div class="indicator" data-v-8ccd545c></div><a class="VPLink link link" href="/docs/quickstart.html" data-v-8ccd545c><!--[--><p class="text" data-v-8ccd545c>Building your first agent</p><!--]--></a><!----></div><!----></div><!--]--></div></section></div><div class="no-transition group" data-v-9c447dd5><section class="VPSidebarItem level-0 collapsible" data-v-9c447dd5 data-v-8ccd545c><div class="item" role="button" tabindex="0" data-v-8ccd545c><div class="indicator" data-v-8ccd545c></div><h2 class="text" data-v-8ccd545c>Integrations</h2><div class="caret" role="button" aria-label="toggle section" tabindex="0" data-v-8ccd545c><span class="vpi-chevron-right caret-icon" data-v-8ccd545c></span></div></div><div class="items" data-v-8ccd545c><!--[--><div class="VPSidebarItem level-1 is-link" data-v-8ccd545c><div class="item" data-v-8ccd545c><div class="indicator" data-v-8ccd545c></div><a class="VPLink link link" href="/docs/guides/github.html" data-v-8ccd545c><!--[--><p class="text" data-v-8ccd545c>GitHub</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-8ccd545c><div class="item" data-v-8ccd545c><div class="indicator" data-v-8ccd545c></div><a class="VPLink link link" href="/docs/guides/slack.html" data-v-8ccd545c><!--[--><p class="text" data-v-8ccd545c>Slack</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-8ccd545c><div class="item" data-v-8ccd545c><div class="indicator" data-v-8ccd545c></div><a class="VPLink link link" href="/docs/guides/webhooks.html" data-v-8ccd545c><!--[--><p class="text" data-v-8ccd545c>Webhooks</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-8ccd545c><div class="item" data-v-8ccd545c><div class="indicator" data-v-8ccd545c></div><a class="VPLink link link" href="/docs/guides/convert-automation.html" data-v-8ccd545c><!--[--><p class="text" data-v-8ccd545c>Cursor Automations</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-8ccd545c><div class="item" data-v-8ccd545c><div class="indicator" data-v-8ccd545c></div><a class="VPLink link link" href="/docs/guides/opentelemetry.html" data-v-8ccd545c><!--[--><p class="text" data-v-8ccd545c>OpenTelemetry</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-8ccd545c><div class="item" data-v-8ccd545c><div class="indicator" data-v-8ccd545c></div><a class="VPLink link link" href="/docs/guides/gitlab.html" data-v-8ccd545c><!--[--><p class="text" data-v-8ccd545c>GitLab</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-8ccd545c><div class="item" data-v-8ccd545c><div class="indicator" data-v-8ccd545c></div><a class="VPLink link link" href="/docs/guides/bitbucket.html" data-v-8ccd545c><!--[--><p class="text" data-v-8ccd545c>Bitbucket</p><!--]--></a><!----></div><!----></div><!--]--></div></section></div><div class="no-transition group" data-v-9c447dd5><section class="VPSidebarItem level-0 collapsible" data-v-9c447dd5 data-v-8ccd545c><div class="item" role="button" tabindex="0" data-v-8ccd545c><div class="indicator" data-v-8ccd545c></div><h2 class="text" data-v-8ccd545c>Extensions</h2><div class="caret" role="button" aria-label="toggle section" tabindex="0" data-v-8ccd545c><span class="vpi-chevron-right caret-icon" data-v-8ccd545c></span></div></div><div class="items" data-v-8ccd545c><!--[--><div class="VPSidebarItem level-1 is-link" data-v-8ccd545c><div class="item" data-v-8ccd545c><div class="indicator" data-v-8ccd545c></div><a class="VPLink link link" href="/docs/reference/extensions.html" data-v-8ccd545c><!--[--><p class="text" data-v-8ccd545c>Overview</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-8ccd545c><div class="item" data-v-8ccd545c><div class="indicator" data-v-8ccd545c></div><a class="VPLink link link" href="/docs/guides/cloud-agents.html" data-v-8ccd545c><!--[--><p class="text" data-v-8ccd545c>Cloud agents</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-8ccd545c><div class="item" data-v-8ccd545c><div class="indicator" data-v-8ccd545c></div><a class="VPLink link link" href="/docs/guides/grokbot-agents.html" data-v-8ccd545c><!--[--><p class="text" data-v-8ccd545c>Grok Bot agents</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-8ccd545c><div class="item" data-v-8ccd545c><div class="indicator" data-v-8ccd545c></div><a class="VPLink link link" href="/docs/guides/improve.html" data-v-8ccd545c><!--[--><p class="text" data-v-8ccd545c>Self-improvement</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-8ccd545c><div class="item" data-v-8ccd545c><div class="indicator" data-v-8ccd545c></div><a class="VPLink link link" href="/docs/guides/jev.html" data-v-8ccd545c><!--[--><p class="text" data-v-8ccd545c>Jev</p><!--]--></a><!----></div><!----></div><!--]--></div></section></div><div class="no-transition group" data-v-9c447dd5><section class="VPSidebarItem level-0 collapsible" data-v-9c447dd5 data-v-8ccd545c><div class="item" role="button" tabindex="0" data-v-8ccd545c><div class="indicator" data-v-8ccd545c></div><h2 class="text" data-v-8ccd545c>Guides</h2><div class="caret" role="button" aria-label="toggle section" tabindex="0" data-v-8ccd545c><span class="vpi-chevron-right caret-icon" data-v-8ccd545c></span></div></div><div class="items" data-v-8ccd545c><!--[--><div class="VPSidebarItem level-1 is-link" data-v-8ccd545c><div class="item" data-v-8ccd545c><div class="indicator" data-v-8ccd545c></div><a class="VPLink link link" href="/docs/guides/mcp-oauth.html" data-v-8ccd545c><!--[--><p class="text" data-v-8ccd545c>MCP</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-8ccd545c><div class="item" data-v-8ccd545c><div class="indicator" data-v-8ccd545c></div><a class="VPLink link link" href="/docs/guides/hooks.html" data-v-8ccd545c><!--[--><p class="text" data-v-8ccd545c>Hooks</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-8ccd545c><div class="item" data-v-8ccd545c><div class="indicator" data-v-8ccd545c></div><a class="VPLink link link" href="/docs/guides/agent-to-agent.html" data-v-8ccd545c><!--[--><p class="text" data-v-8ccd545c>Peer agents</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-8ccd545c><div class="item" data-v-8ccd545c><div class="indicator" data-v-8ccd545c></div><a class="VPLink link link" href="/docs/deployment.html" data-v-8ccd545c><!--[--><p class="text" data-v-8ccd545c>Deployment</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-8ccd545c><div class="item" data-v-8ccd545c><div class="indicator" data-v-8ccd545c></div><a class="VPLink link link" href="/docs/guides/migrate.html" data-v-8ccd545c><!--[--><p class="text" data-v-8ccd545c>Early-alpha migration</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-8ccd545c><div class="item" data-v-8ccd545c><div class="indicator" data-v-8ccd545c></div><a class="VPLink link link" href="/docs/evals.html" data-v-8ccd545c><!--[--><p class="text" data-v-8ccd545c>Evals</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-8ccd545c><div class="item" data-v-8ccd545c><div class="indicator" data-v-8ccd545c></div><a class="VPLink link link" href="/docs/hillclimbing.html" data-v-8ccd545c><!--[--><p class="text" data-v-8ccd545c>Hillclimbing</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-8ccd545c><div class="item" data-v-8ccd545c><div class="indicator" data-v-8ccd545c></div><a class="VPLink link link" href="/docs/building-with-agents.html" data-v-8ccd545c><!--[--><p class="text" data-v-8ccd545c>Build with a coding agent</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-8ccd545c><div class="item" data-v-8ccd545c><div class="indicator" data-v-8ccd545c></div><a class="VPLink link link" href="/docs/troubleshooting.html" data-v-8ccd545c><!--[--><p class="text" data-v-8ccd545c>Troubleshooting</p><!--]--></a><!----></div><!----></div><!--]--></div></section></div><div class="no-transition group" data-v-9c447dd5><section class="VPSidebarItem level-0 collapsible" data-v-9c447dd5 data-v-8ccd545c><div class="item" role="button" tabindex="0" data-v-8ccd545c><div class="indicator" data-v-8ccd545c></div><h2 class="text" data-v-8ccd545c>Templates</h2><div class="caret" role="button" aria-label="toggle section" tabindex="0" data-v-8ccd545c><span class="vpi-chevron-right caret-icon" data-v-8ccd545c></span></div></div><div class="items" data-v-8ccd545c><!--[--><div class="VPSidebarItem level-1 is-link" data-v-8ccd545c><div class="item" data-v-8ccd545c><div class="indicator" data-v-8ccd545c></div><a class="VPLink link link" href="/docs/templates/grokbot-agents.html" data-v-8ccd545c><!--[--><p class="text" data-v-8ccd545c>Grok Bot agents</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-8ccd545c><div class="item" data-v-8ccd545c><div class="indicator" data-v-8ccd545c></div><a class="VPLink link link" href="/docs/templates/security-reviewer.html" data-v-8ccd545c><!--[--><p class="text" data-v-8ccd545c>Security reviewer</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-8ccd545c><div class="item" data-v-8ccd545c><div class="indicator" data-v-8ccd545c></div><a class="VPLink link link" href="/docs/templates/thermo-review.html" data-v-8ccd545c><!--[--><p class="text" data-v-8ccd545c>Thermo review</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-8ccd545c><div class="item" data-v-8ccd545c><div class="indicator" data-v-8ccd545c></div><a class="VPLink link link" href="/docs/templates/thermo-quality-review.html" data-v-8ccd545c><!--[--><p class="text" data-v-8ccd545c>Thermo quality review</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-8ccd545c><div class="item" data-v-8ccd545c><div class="indicator" data-v-8ccd545c></div><a class="VPLink link link" href="/docs/templates/agentic-owners.html" data-v-8ccd545c><!--[--><p class="text" data-v-8ccd545c>Agentic Approver</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-8ccd545c><div class="item" data-v-8ccd545c><div class="indicator" data-v-8ccd545c></div><a class="VPLink link link" href="/docs/templates/triage.html" data-v-8ccd545c><!--[--><p class="text" data-v-8ccd545c>Triage agent</p><!--]--></a><!----></div><!----></div><!--]--></div></section></div><div class="no-transition group" data-v-9c447dd5><section class="VPSidebarItem level-0 collapsible has-active" data-v-9c447dd5 data-v-8ccd545c><div class="item" role="button" tabindex="0" data-v-8ccd545c><div class="indicator" data-v-8ccd545c></div><h2 class="text" data-v-8ccd545c>Reference</h2><div class="caret" role="button" aria-label="toggle section" tabindex="0" data-v-8ccd545c><span class="vpi-chevron-right caret-icon" data-v-8ccd545c></span></div></div><div class="items" data-v-8ccd545c><!--[--><div class="VPSidebarItem level-1 is-link" data-v-8ccd545c><div class="item" data-v-8ccd545c><div class="indicator" data-v-8ccd545c></div><a class="VPLink link link" href="/docs/reference/project-layout.html" data-v-8ccd545c><!--[--><p class="text" data-v-8ccd545c>Project layout</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-8ccd545c><div class="item" data-v-8ccd545c><div class="indicator" data-v-8ccd545c></div><a class="VPLink link link" href="/docs/reference/agent-config.html" data-v-8ccd545c><!--[--><p class="text" data-v-8ccd545c>Agent config</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-8ccd545c><div class="item" data-v-8ccd545c><div class="indicator" data-v-8ccd545c></div><a class="VPLink link link" href="/docs/reference/instructions.html" data-v-8ccd545c><!--[--><p class="text" data-v-8ccd545c>Instructions</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-8ccd545c><div class="item" data-v-8ccd545c><div class="indicator" data-v-8ccd545c></div><a class="VPLink link link" href="/docs/reference/tools.html" data-v-8ccd545c><!--[--><p class="text" data-v-8ccd545c>Tools</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-8ccd545c><div class="item" data-v-8ccd545c><div class="indicator" data-v-8ccd545c></div><a class="VPLink link link" href="/docs/reference/prompt.html" data-v-8ccd545c><!--[--><p class="text" data-v-8ccd545c>prompt</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-8ccd545c><div class="item" data-v-8ccd545c><div class="indicator" data-v-8ccd545c></div><a class="VPLink link link" href="/docs/reference/skills.html" data-v-8ccd545c><!--[--><p class="text" data-v-8ccd545c>Skills</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-8ccd545c><div class="item" data-v-8ccd545c><div class="indicator" data-v-8ccd545c></div><a class="VPLink link link" href="/docs/reference/connections.html" data-v-8ccd545c><!--[--><p class="text" data-v-8ccd545c>MCP Connections</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-8ccd545c><div class="item" data-v-8ccd545c><div class="indicator" data-v-8ccd545c></div><a class="VPLink link link" href="/docs/reference/subagents.html" data-v-8ccd545c><!--[--><p class="text" data-v-8ccd545c>Subagents</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-8ccd545c><div class="item" data-v-8ccd545c><div class="indicator" data-v-8ccd545c></div><a class="VPLink link link" href="/docs/reference/channels.html" data-v-8ccd545c><!--[--><p class="text" data-v-8ccd545c>Channels</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-8ccd545c><div class="item" data-v-8ccd545c><div class="indicator" data-v-8ccd545c></div><a class="VPLink link link" href="/docs/reference/schedules.html" data-v-8ccd545c><!--[--><p class="text" data-v-8ccd545c>Schedules & reminders</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-8ccd545c><div class="item" data-v-8ccd545c><div class="indicator" data-v-8ccd545c></div><a class="VPLink link link" href="/docs/reference/hooks.html" data-v-8ccd545c><!--[--><p class="text" data-v-8ccd545c>Hooks</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-8ccd545c><div class="item" data-v-8ccd545c><div class="indicator" data-v-8ccd545c></div><a class="VPLink link link" href="/docs/reference/evals.html" data-v-8ccd545c><!--[--><p class="text" data-v-8ccd545c>Evals</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-8ccd545c><div class="item" data-v-8ccd545c><div class="indicator" data-v-8ccd545c></div><a class="VPLink link link" href="/docs/reference/artifacts.html" data-v-8ccd545c><!--[--><p class="text" data-v-8ccd545c>Artifacts</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-8ccd545c><div class="item" data-v-8ccd545c><div class="indicator" data-v-8ccd545c></div><a class="VPLink link link" href="/docs/reference/sessions.html" data-v-8ccd545c><!--[--><p class="text" data-v-8ccd545c>Sessions & streaming</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-8ccd545c><div class="item" data-v-8ccd545c><div class="indicator" data-v-8ccd545c></div><a class="VPLink link link" href="/docs/reference/playground.html" data-v-8ccd545c><!--[--><p class="text" data-v-8ccd545c>Playground</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-8ccd545c><div class="item" data-v-8ccd545c><div class="indicator" data-v-8ccd545c></div><a class="VPLink link link" href="/docs/reference/cli.html" data-v-8ccd545c><!--[--><p class="text" data-v-8ccd545c>CLI</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-8ccd545c><div class="item" data-v-8ccd545c><div class="indicator" data-v-8ccd545c></div><a class="VPLink link link" href="/docs/reference/http-api.html" data-v-8ccd545c><!--[--><p class="text" data-v-8ccd545c>HTTP API</p><!--]--></a><!----></div><!----></div><!--]--></div></section></div><!--]--><!--[--><!--]--></nav></aside><div class="VPContent has-sidebar" id="VPContent" data-v-5ebc75e4 data-v-4ab733be><div class="VPDoc has-sidebar has-aside" data-v-4ab733be data-v-4e7466dc><!--[--><!--]--><div class="container" data-v-4e7466dc><div class="aside" data-v-4e7466dc><div class="aside-curtain" data-v-4e7466dc></div><div class="aside-container" data-v-4e7466dc><div class="aside-content" data-v-4e7466dc><div class="VPDocAside" data-v-4e7466dc data-v-4f3f9a30><!--[--><!--]--><!--[--><!--]--><nav aria-labelledby="doc-outline-aria-label" class="VPDocAsideOutline" data-v-4f3f9a30 data-v-aacbb3fc><div class="content" data-v-aacbb3fc><div class="outline-marker" data-v-aacbb3fc></div><div aria-level="2" class="outline-title" id="doc-outline-aria-label" role="heading" data-v-aacbb3fc>On this page</div><ul class="VPDocOutlineItem root" data-v-aacbb3fc data-v-0ffefe2a><!--[--><!--]--></ul></div></nav><!--[--><!--]--><div class="spacer" data-v-4f3f9a30></div><!--[--><!--]--><!----><!--[--><!--]--><!--[--><!--]--></div></div></div></div><div class="content" data-v-4e7466dc><div class="content-container" data-v-4e7466dc><!--[--><!--]--><main class="main" data-v-4e7466dc><div style="position:relative;" class="vp-doc _docs_reference_hooks" data-v-4e7466dc><div><h1 id="hooks" tabindex="-1">Hooks <a class="header-anchor" href="#hooks" aria-label="Permalink to &quot;Hooks&quot;">​</a></h1><p>A hook subscribes to selected session events and can run a side effect after each matching event is recorded: an audit line, a metric, a transcript copy, or derived state. Hooks run in the serving process for every session of the agent. They cannot change the turn, the prompt, or the reply; a handler that throws is logged and skipped.</p><p>Treat the event as read-only. Later subscribers see the same object. That makes hooks safe to add to a production agent, and the wrong surface for anything that must run before the model or must fail a turn; see <a href="#hook-boundaries">Hook boundaries</a>.</p><p><code>defineHook</code> is unrelated to <a href="https://cursor.com/docs/agent/hooks" target="_blank" rel="noreferrer">Cursor Agent hooks</a>, the <code>.cursor/hooks.json</code> scripts that can observe, block, or modify the agent loop. Those still run inside a local session workspace.</p><h2 id="author-a-hook" tabindex="-1">Author a hook <a class="header-anchor" href="#author-a-hook" aria-label="Permalink to &quot;Author a hook&quot;">​</a></h2><p>Author <code>bot/hooks/&lt;name&gt;.ts</code> with <code>defineHook</code> from <code>@cursor/bdk/hooks</code>. This one meters tokens:</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// bot/hooks/usage.ts</span></span>
 <span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { defineHook } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;@cursor/bdk/hooks&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
 <span class="line"></span>
 <span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">export</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> default</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> defineHook</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
@@ -70,7 +70,7 @@
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">      ctx.host.otel.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">increment</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;acme.turn.failed&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, { channel: ctx.channel.id });</span></span>
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    },</span></span>
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  },</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><p>Any module under <code>bot/hooks/</code>, subfolders included, is a hook named by its path without the extension: <code>bot/hooks/audit/usage.ts</code> is <code>audit/usage</code>. <code>*.test.ts</code> and <code>*.spec.ts</code> files are skipped. The default export must be <code>defineHook(...)</code>, names can&#39;t contain <code>__</code>, and an empty <code>events</code> map skips the hook with a warning; <code>bdk validate</code> reports all three. An extension mounts its hooks as <code>&lt;ns&gt;__&lt;name&gt;</code>, and <code>disableHook()</code> removes one (<a href="./extensions.html#adjust-a-mounted-extension">Adjust a mounted extension</a>).</p><p><code>bdk init</code> scaffolds <code>bot/hooks/memory.ts</code>, which exports <code>memoryHook()</code> from <code>@cursor/bdk/memory</code> and journals every turn for later sessions to read. Delete the file to opt out.</p><h2 id="events-and-payloads" tabindex="-1">Events and payloads <a class="header-anchor" href="#events-and-payloads" aria-label="Permalink to &quot;Events and payloads&quot;">​</a></h2><p>Keys are event types from the <a href="./sessions.html#stream-events">event vocabulary</a>, or <code>&quot;*&quot;</code> for every event. A typed key narrows <code>event.data</code>; a <code>&quot;*&quot;</code> handler receives the union, so switch on <code>event.type</code>. Every event carries the stream envelope <code>{ type, index, sessionId, turnId?, at, data }</code>, with <code>turnId</code> set on turn-scoped events. Skip <code>*.appended</code> deltas when you want the final text; <code>message.completed</code> already has it.</p><table tabindex="0"><thead><tr><th>Event</th><th><code>event.data</code></th></tr></thead><tbody><tr><td><code>message.received</code></td><td><code>{ text }</code></td></tr><tr><td><code>turn.completed</code></td><td><code>{ result?, usage?, cost? }</code>. <code>usage</code> has <code>inputTokens</code>, <code>outputTokens</code>, <code>cacheReadTokens</code>, <code>cacheWriteTokens</code>, and optional <code>reasoningTokens</code>. <code>cost</code> has <code>totalUsd</code> and the <code>model</code> it was priced against</td></tr><tr><td><code>turn.failed</code></td><td><code>{ message, status? }</code>. <code>status</code> is <code>&quot;error&quot;</code> or <code>&quot;cancelled&quot;</code> when present</td></tr><tr><td><code>actions.requested</code></td><td><code>{ calls: [{ callId, toolName, args?, parentCallId? }], parentCallId? }</code>. One envelope per model step once that step has listed its tools. A single tool is a batch of one. <code>parentCallId</code> marks subagent work</td></tr><tr><td><code>actions.completed</code></td><td><code>{ results: [{ callId, toolName, output?, isError, stubbed?, parentCallId? }], parentCallId? }</code>. Pair with <code>actions.requested</code>; emitted when every call in that batch has a result</td></tr><tr><td><code>action.result</code></td><td><code>{ callId, toolName, output?, isError, stubbed?, parentCallId? }</code>. Live per-call envelope for chips and spans. <code>stubbed</code> means a dry-run session answered a write without running it</td></tr></tbody></table><p>The types are <code>SessionEvent</code>, <code>SessionEventType</code>, and <code>HookContext</code>, exported from <code>@cursor/bdk</code>.</p><h2 id="handler-context" tabindex="-1">Handler context <a class="header-anchor" href="#handler-context" aria-label="Permalink to &quot;Handler context&quot;">​</a></h2><table tabindex="0"><thead><tr><th>Member</th><th>What it is</th></tr></thead><tbody><tr><td><code>ctx.session</code></td><td>Read-only session info: <code>id</code>, <code>channelId</code>, <code>mode</code> (<code>chat</code> or <code>task</code>), <code>purpose</code> (<code>live</code> or <code>eval</code>), <code>auth</code>, plus <code>title</code> and <code>sdkAgentId</code> when set</td></tr><tr><td><code>ctx.agent</code></td><td><code>{ name }</code> of the agent the event belongs to</td></tr><tr><td><code>ctx.channel</code></td><td><code>{ id, continuationToken }</code>. The token is <code>null</code> when the session can&#39;t take follow-ups</td></tr><tr><td><code>ctx.host.kv</code></td><td>Durable JSON, shared by every session of the agent. Prefix keys with <code>ctx.session.id</code> for per-session state</td></tr><tr><td><code>ctx.host.files</code></td><td>Durable files, bound to this session. Pass <code>{ scope: &quot;deployment&quot; }</code> for agent-wide files</td></tr><tr><td><code>ctx.host.otel</code></td><td>Counters, histograms, and tags, attributed to this session</td></tr><tr><td><code>ctx.host.mcp</code>, <code>ctx.host.github</code>, <code>ctx.host.slack</code></td><td>The same shared clients tools get</td></tr><tr><td><code>ctx.host.reminders</code></td><td>Per-session <a href="./schedules.html#reminders">reminders</a>, the same API tools get</td></tr><tr><td><code>ctx.artifacts</code></td><td>Session-bound <a href="./artifacts.html">artifacts</a> facade: <code>tag</code> fills in <code>sessionId</code> and <code>turnId</code></td></tr><tr><td><code>ctx.stateRoot</code></td><td>Absolute path of the local state root. It resets when a hosted deployment is replaced; keep derived state in <code>kv</code> or <code>files</code></td></tr></tbody></table><h2 id="hook-dispatch" tabindex="-1">Hook dispatch <a class="header-anchor" href="#hook-dispatch" aria-label="Permalink to &quot;Hook dispatch&quot;">​</a></h2><p>A hook runs after the event is recorded. It never delays the model and never sees an event that wasn&#39;t recorded.</p><table tabindex="0"><thead><tr><th>Rule</th><th>What happens</th></tr></thead><tbody><tr><td>Same session</td><td>Events dispatch one at a time</td></tr><tr><td>Eval sessions</td><td>The same stream fires; skip metering or paging when <code>ctx.session.purpose === &quot;eval&quot;</code></td></tr><tr><td>Host restart</td><td>Recorded events are not replayed into hooks, so a mirror needs no dedupe</td></tr><tr><td>Slow handler</td><td>Holds the next event&#39;s handlers on that session, not the model. Keep handlers short and queue anything slow</td></tr></tbody></table><p>Read hosted secrets inside the handler, not at module scope. Give outbound calls a timeout; a stalled request holds later handlers on that session. Skip cancelled turns when paging; they record interrupted work.</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// bot/hooks/page-on-failure.ts</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><p>Any module under <code>bot/hooks/</code>, subfolders included, is a hook named by its path without the extension: <code>bot/hooks/audit/usage.ts</code> is <code>audit/usage</code>. <code>*.test.ts</code> and <code>*.spec.ts</code> files are skipped. The default export must be <code>defineHook(...)</code>, names can&#39;t contain <code>__</code>, and an empty <code>events</code> map skips the hook with a warning; <code>bdk validate</code> reports all three. An extension mounts its hooks as <code>&lt;ns&gt;__&lt;name&gt;</code>, and <code>disableHook()</code> removes one (<a href="./extensions.html#adjust-a-mounted-extension">Adjust a mounted extension</a>).</p><p><code>bdk init</code> scaffolds <code>bot/hooks/memory.ts</code>, which exports <code>memoryHook()</code> from <code>@cursor/bdk/memory</code> and journals every turn for later sessions to read. Delete the file to opt out.</p><h2 id="events-and-payloads" tabindex="-1">Events and payloads <a class="header-anchor" href="#events-and-payloads" aria-label="Permalink to &quot;Events and payloads&quot;">​</a></h2><p>Keys are event types from the <a href="./sessions.html#stream-events">event vocabulary</a>, or <code>&quot;*&quot;</code> for every event. A typed key narrows <code>event.data</code>; a <code>&quot;*&quot;</code> handler receives the union, so switch on <code>event.type</code>. Every event carries the stream envelope <code>{ type, index, sessionId, turnId?, at, data }</code>, with <code>turnId</code> set on turn-scoped events. Skip <code>*.appended</code> deltas when you want the final text; <code>message.completed</code> already has it.</p><table tabindex="0"><thead><tr><th>Event</th><th><code>event.data</code></th></tr></thead><tbody><tr><td><code>message.received</code></td><td><code>{ text }</code></td></tr><tr><td><code>turn.completed</code></td><td><code>{ result?, usage?, cost? }</code>. <code>usage</code> has <code>inputTokens</code>, <code>outputTokens</code>, <code>cacheReadTokens</code>, <code>cacheWriteTokens</code>, and optional <code>reasoningTokens</code>. <code>cost</code> has <code>totalUsd</code> and the <code>model</code> it was priced against</td></tr><tr><td><code>turn.failed</code></td><td><code>{ message, status? }</code>. <code>status</code> is <code>&quot;error&quot;</code> or <code>&quot;cancelled&quot;</code> when present</td></tr><tr><td><code>actions.requested</code></td><td><code>{ calls: [{ callId, toolName, args?, parentCallId? }], parentCallId? }</code>. One envelope per model step once that step has listed its tools. A single tool is a batch of one. <code>parentCallId</code> marks subagent work</td></tr><tr><td><code>actions.completed</code></td><td><code>{ results: [{ callId, toolName, output?, isError, stubbed?, parentCallId? }], parentCallId? }</code>. Pair with <code>actions.requested</code>; emitted when every call in that batch has a result</td></tr><tr><td><code>action.result</code></td><td><code>{ callId, toolName, output?, isError, stubbed?, parentCallId? }</code>. Live per-call envelope for chips and spans. <code>stubbed</code> means a dry-run session answered a write without running it</td></tr><tr><td><code>action.tool_retry</code></td><td><code>{ callId, toolName, attempt, reason, connection? }</code>. A read is running again after a transient failure. <code>attempt</code> is the try about to run. <code>reason</code> is a class such as <code>transport</code> or <code>http_503</code></td></tr></tbody></table><p>The types are <code>SessionEvent</code>, <code>SessionEventType</code>, and <code>HookContext</code>, exported from <code>@cursor/bdk</code>.</p><h2 id="handler-context" tabindex="-1">Handler context <a class="header-anchor" href="#handler-context" aria-label="Permalink to &quot;Handler context&quot;">​</a></h2><table tabindex="0"><thead><tr><th>Member</th><th>What it is</th></tr></thead><tbody><tr><td><code>ctx.session</code></td><td>Read-only session info: <code>id</code>, <code>channelId</code>, <code>mode</code> (<code>chat</code> or <code>task</code>), <code>purpose</code> (<code>live</code> or <code>eval</code>), <code>auth</code>, plus <code>title</code> and <code>sdkAgentId</code> when set</td></tr><tr><td><code>ctx.agent</code></td><td><code>{ name }</code> of the agent the event belongs to</td></tr><tr><td><code>ctx.channel</code></td><td><code>{ id, continuationToken }</code>. The token is <code>null</code> when the session can&#39;t take follow-ups</td></tr><tr><td><code>ctx.host.kv</code></td><td>Durable JSON, shared by every session of the agent. Prefix keys with <code>ctx.session.id</code> for per-session state</td></tr><tr><td><code>ctx.host.files</code></td><td>Durable files, bound to this session. Pass <code>{ scope: &quot;deployment&quot; }</code> for agent-wide files</td></tr><tr><td><code>ctx.host.otel</code></td><td>Counters, histograms, and tags, attributed to this session</td></tr><tr><td><code>ctx.host.mcp</code>, <code>ctx.host.github</code>, <code>ctx.host.slack</code></td><td>The same shared clients tools get</td></tr><tr><td><code>ctx.host.reminders</code></td><td>Per-session <a href="./schedules.html#reminders">reminders</a>, the same API tools get</td></tr><tr><td><code>ctx.artifacts</code></td><td>Session-bound <a href="./artifacts.html">artifacts</a> facade: <code>tag</code> fills in <code>sessionId</code> and <code>turnId</code></td></tr><tr><td><code>ctx.stateRoot</code></td><td>Absolute path of the local state root. It resets when a hosted deployment is replaced; keep derived state in <code>kv</code> or <code>files</code></td></tr></tbody></table><h2 id="hook-dispatch" tabindex="-1">Hook dispatch <a class="header-anchor" href="#hook-dispatch" aria-label="Permalink to &quot;Hook dispatch&quot;">​</a></h2><p>A hook runs after the event is recorded. It never delays the model and never sees an event that wasn&#39;t recorded.</p><table tabindex="0"><thead><tr><th>Rule</th><th>What happens</th></tr></thead><tbody><tr><td>Same session</td><td>Events dispatch one at a time</td></tr><tr><td>Eval sessions</td><td>The same stream fires; skip metering or paging when <code>ctx.session.purpose === &quot;eval&quot;</code></td></tr><tr><td>Host restart</td><td>Recorded events are not replayed into hooks, so a mirror needs no dedupe</td></tr><tr><td>Slow handler</td><td>Holds the next event&#39;s handlers on that session, not the model. Keep handlers short and queue anything slow</td></tr></tbody></table><p>Read hosted secrets inside the handler, not at module scope. Give outbound calls a timeout; a stalled request holds later handlers on that session. Skip cancelled turns when paging; they record interrupted work.</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// bot/hooks/page-on-failure.ts</span></span>
 <span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { defineHook } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;@cursor/bdk/hooks&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
 <span class="line"></span>
 <span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">export</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> default</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> defineHook</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
@@ -97,8 +97,8 @@
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">      });</span></span>
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    },</span></span>
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  },</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><h2 id="hooks-vs-channels-vs-evals" tabindex="-1">Hooks vs channels vs evals <a class="header-anchor" href="#hooks-vs-channels-vs-evals" aria-label="Permalink to &quot;Hooks vs channels vs evals&quot;">​</a></h2><p>All three consume the same stream, for different jobs:</p><table tabindex="0"><thead><tr><th></th><th>Hooks</th><th>Channel <code>events</code></th><th>Evals</th></tr></thead><tbody><tr><td>Scope</td><td>every session of the agent</td><td>sessions the channel owns</td><td>one test turn</td></tr><tr><td>Job</td><td>observe: audit, metrics, mirrors, derived state</td><td>deliver: replies back to the channel&#39;s surface</td><td>assert: gates over the trajectory</td></tr><tr><td>Context</td><td><code>ctx.host</code>, <code>ctx.artifacts</code>, session info</td><td><code>channel.state</code>, <code>setContinuationToken</code>, <code>ctx.host</code>, session info</td><td>the <code>t</code> assertion helpers</td></tr><tr><td>Can affect the run</td><td>no</td><td>yes, it owns the surface</td><td>n/a</td></tr><tr><td>Authored at</td><td><code>bot/hooks/*.ts</code></td><td>channel config</td><td><code>evals/**/*.eval.ts</code></td></tr></tbody></table><h2 id="hook-boundaries" tabindex="-1">Hook boundaries <a class="header-anchor" href="#hook-boundaries" aria-label="Permalink to &quot;Hook boundaries&quot;">​</a></h2><table tabindex="0"><thead><tr><th>You want to</th><th>Use instead</th></tr></thead><tbody><tr><td>Add context before the model runs</td><td>The channel&#39;s <code>send</code> message and <code>workspaceFiles</code>, <code>instructions.md</code>, skills, or <code>sandbox/workspace/</code> seed files</td></tr><tr><td>Reply on Slack, comment on a PR, or post any other delivery</td><td>The channel&#39;s <code>events</code> map, or the Slack and GitHub packs</td></tr><tr><td>Show PR progress (merge-box check, sticky banner)</td><td><code>githubChannel({ progress: { commitStatus, banner } })</code>; see <a href="./../guides/github.html">GitHub agents</a></td></tr><tr><td>Block, approve, or rewrite a tool call</td><td><a href="./tools.html#gate-a-tool-on-human-approval"><code>needsApproval</code></a> on the tool</td></tr><tr><td>Act on the final assistant text, reject it for a same-turn repair, or fail a bad turn</td><td><code>defineResult</code></td></tr><tr><td>Gate a change on behavior</td><td><a href="./../evals.html">Evals</a></td></tr></tbody></table><h2 id="test-a-hook" tabindex="-1">Test a hook <a class="header-anchor" href="#test-a-hook" aria-label="Permalink to &quot;Test a hook&quot;">​</a></h2><p>A hook definition is a plain object, so a unit test calls <code>hook.events[&quot;turn.completed&quot;]</code> directly with an event and a stub <code>HookContext</code>. Discovery skips <code>*.test.ts</code>, so the test can live next to the hook.</p><table tabindex="0"><thead><tr><th>Command</th><th>What it reports</th></tr></thead><tbody><tr><td><code>bdk validate --dir .</code></td><td>Discovery errors and the empty-handlers warning</td></tr><tr><td><code>bdk info --dir . --json</code></td><td>Loaded hooks under <code>agents[].hooks</code></td></tr><tr><td><code>bdk run --dir . --message &quot;…&quot;</code></td><td>Serve log on stderr, including <code>hook &quot;&lt;name&gt;&quot; handler for &lt;event&gt; threw: …</code></td></tr></tbody></table><p>On hosting, read the same log with <a href="./cli.html#logs"><code>bdk logs</code></a>.</p><h2 id="related" tabindex="-1">Related <a class="header-anchor" href="#related" aria-label="Permalink to &quot;Related&quot;">​</a></h2><ul><li><a href="./../guides/hooks.html">Hooks guide</a>: meter usage and page on failure</li><li><a href="./sessions.html">Sessions and streaming</a>: the event vocabulary hooks observe</li><li><a href="./../guides/opentelemetry.html">OpenTelemetry</a>: OTLP traces and metrics from the same event stream</li><li><a href="./../deployment.html#observability">Deployment</a>: runtime logs and export paths</li><li><a href="./channels.html#events">Channels</a>: the delivery-side counterpart</li></ul></div></div></main><footer class="VPDocFooter" data-v-afe580da data-v-feab96e0><!--[--><!--]--><!----><nav class="prev-next" aria-labelledby="doc-footer-aria-label" data-v-feab96e0><span class="visually-hidden" id="doc-footer-aria-label" data-v-feab96e0>Pager</span><div class="pager" data-v-feab96e0><a class="VPLink link pager-link prev" href="/docs/reference/schedules.html" data-v-feab96e0><!--[--><span class="desc" data-v-feab96e0>Previous page</span><span class="title" data-v-feab96e0>Schedules & reminders</span><!--]--></a></div><div class="pager" data-v-feab96e0><a class="VPLink link pager-link next" href="/docs/reference/evals.html" data-v-feab96e0><!--[--><span class="desc" data-v-feab96e0>Next page</span><span class="title" data-v-feab96e0>Evals</span><!--]--></a></div></nav></footer><!--[--><!--]--></div></div></div><!--[--><!--]--></div></div><!----><!--[--><!--]--></div></div>
-    <script>window.__VP_HASH_MAP__=JSON.parse("{\"building-with-agents.md\":\"Df87rAe1\",\"deployment.md\":\"BYuEcDBv\",\"evals.md\":\"C851kViu\",\"guides_agent-to-agent.md\":\"Cps5NiCV\",\"guides_bitbucket.md\":\"CKUayYtD\",\"guides_cloud-agents.md\":\"CWJjS9No\",\"guides_convert-automation.md\":\"DMEX9nF-\",\"guides_github.md\":\"TuNiZAOQ\",\"guides_gitlab.md\":\"CtNI4fSH\",\"guides_grokbot-agents.md\":\"tD1smFhU\",\"guides_hooks.md\":\"5Ce3NXxZ\",\"guides_improve.md\":\"CRrYq22s\",\"guides_jev.md\":\"D7XH4JH3\",\"guides_mcp-oauth.md\":\"DR3zhC9r\",\"guides_migrate.md\":\"sCAvvlC6\",\"guides_opentelemetry.md\":\"jcPNrQbH\",\"guides_slack.md\":\"Bn-WupSE\",\"guides_webhooks.md\":\"BBvAm_VF\",\"hillclimbing.md\":\"Dxvd-0gT\",\"index.md\":\"Dxxr7pFa\",\"quickstart.md\":\"BK5gjHM2\",\"reference_agent-config.md\":\"DrtLxWgR\",\"reference_artifacts.md\":\"DLV9MZES\",\"reference_channels.md\":\"LbNIJBwd\",\"reference_cli.md\":\"dYCAL2lB\",\"reference_connections.md\":\"Bljpve-y\",\"reference_evals.md\":\"D5i8PuXJ\",\"reference_extensions.md\":\"OUacPetl\",\"reference_hooks.md\":\"C5LCJ1R3\",\"reference_http-api.md\":\"DbFNOubV\",\"reference_instructions.md\":\"DrcHZXig\",\"reference_playground.md\":\"1hx0gcIu\",\"reference_project-layout.md\":\"C2JMRh7p\",\"reference_prompt.md\":\"DqPh71XN\",\"reference_schedules.md\":\"BuJ8fgMa\",\"reference_sessions.md\":\"CM5zo3w4\",\"reference_skills.md\":\"C0guGcH0\",\"reference_subagents.md\":\"gmPt5J-M\",\"reference_tools.md\":\"v3SXVSs_\",\"templates_agentic-owners.md\":\"CvmABtia\",\"templates_grokbot-agents.md\":\"2sydjFiO\",\"templates_security-reviewer.md\":\"Gh6EF9Us\",\"templates_thermo-quality-review.md\":\"B77UyTrX\",\"templates_thermo-review.md\":\"DRJ7mC5U\",\"templates_triage.md\":\"CNN6b0JZ\",\"troubleshooting.md\":\"x-GBa7wN\"}");window.__VP_SITE_DATA__=JSON.parse("{\"lang\":\"en-US\",\"dir\":\"ltr\",\"title\":\"Grok Bot Development Kit (BDK)\",\"description\":\"Build and serve bots and agents from versioned Markdown and TypeScript.\",\"base\":\"/docs/\",\"head\":[],\"router\":{\"prefetchLinks\":true},\"appearance\":true,\"themeConfig\":{\"sdkVersion\":\"0.2.10\",\"nav\":[{\"text\":\"Quickstart\",\"link\":\"/quickstart\"},{\"text\":\"Guides\",\"link\":\"/guides/mcp-oauth\"},{\"text\":\"Integrations\",\"link\":\"/guides/github\"},{\"text\":\"Templates\",\"link\":\"/templates/security-reviewer\"},{\"text\":\"Reference\",\"link\":\"/reference/project-layout\"}],\"search\":{\"provider\":\"local\"},\"outline\":{\"level\":[2,3]},\"sidebar\":[{\"text\":\"Getting started\",\"items\":[{\"text\":\"Overview\",\"link\":\"/\"},{\"text\":\"Building your first agent\",\"link\":\"/quickstart\"}]},{\"text\":\"Integrations\",\"collapsed\":false,\"items\":[{\"text\":\"GitHub\",\"link\":\"/guides/github\"},{\"text\":\"Slack\",\"link\":\"/guides/slack\"},{\"text\":\"Webhooks\",\"link\":\"/guides/webhooks\"},{\"text\":\"Cursor Automations\",\"link\":\"/guides/convert-automation\"},{\"text\":\"OpenTelemetry\",\"link\":\"/guides/opentelemetry\"},{\"text\":\"GitLab\",\"link\":\"/guides/gitlab\"},{\"text\":\"Bitbucket\",\"link\":\"/guides/bitbucket\"}]},{\"text\":\"Extensions\",\"collapsed\":false,\"items\":[{\"text\":\"Overview\",\"link\":\"/reference/extensions\"},{\"text\":\"Cloud agents\",\"link\":\"/guides/cloud-agents\"},{\"text\":\"Grok Bot agents\",\"link\":\"/guides/grokbot-agents\"},{\"text\":\"Self-improvement\",\"link\":\"/guides/improve\"},{\"text\":\"Jev\",\"link\":\"/guides/jev\"}]},{\"text\":\"Guides\",\"collapsed\":false,\"items\":[{\"text\":\"MCP\",\"link\":\"/guides/mcp-oauth\"},{\"text\":\"Hooks\",\"link\":\"/guides/hooks\"},{\"text\":\"Peer agents\",\"link\":\"/guides/agent-to-agent\"},{\"text\":\"Deployment\",\"link\":\"/deployment\"},{\"text\":\"Early-alpha migration\",\"link\":\"/guides/migrate\"},{\"text\":\"Evals\",\"link\":\"/evals\"},{\"text\":\"Hillclimbing\",\"link\":\"/hillclimbing\"},{\"text\":\"Build with a coding agent\",\"link\":\"/building-with-agents\"},{\"text\":\"Troubleshooting\",\"link\":\"/troubleshooting\"}]},{\"text\":\"Templates\",\"collapsed\":false,\"items\":[{\"text\":\"Grok Bot agents\",\"link\":\"/templates/grokbot-agents\"},{\"text\":\"Security reviewer\",\"link\":\"/templates/security-reviewer\"},{\"text\":\"Thermo review\",\"link\":\"/templates/thermo-review\"},{\"text\":\"Thermo quality review\",\"link\":\"/templates/thermo-quality-review\"},{\"text\":\"Agentic Approver\",\"link\":\"/templates/agentic-owners\"},{\"text\":\"Triage agent\",\"link\":\"/templates/triage\"}]},{\"text\":\"Reference\",\"collapsed\":false,\"items\":[{\"text\":\"Project layout\",\"link\":\"/reference/project-layout\"},{\"text\":\"Agent config\",\"link\":\"/reference/agent-config\"},{\"text\":\"Instructions\",\"link\":\"/reference/instructions\"},{\"text\":\"Tools\",\"link\":\"/reference/tools\"},{\"text\":\"prompt\",\"link\":\"/reference/prompt\"},{\"text\":\"Skills\",\"link\":\"/reference/skills\"},{\"text\":\"MCP Connections\",\"link\":\"/reference/connections\"},{\"text\":\"Subagents\",\"link\":\"/reference/subagents\"},{\"text\":\"Channels\",\"link\":\"/reference/channels\"},{\"text\":\"Schedules & reminders\",\"link\":\"/reference/schedules\"},{\"text\":\"Hooks\",\"link\":\"/reference/hooks\"},{\"text\":\"Evals\",\"link\":\"/reference/evals\"},{\"text\":\"Artifacts\",\"link\":\"/reference/artifacts\"},{\"text\":\"Sessions & streaming\",\"link\":\"/reference/sessions\"},{\"text\":\"Playground\",\"link\":\"/reference/playground\"},{\"text\":\"CLI\",\"link\":\"/reference/cli\"},{\"text\":\"HTTP API\",\"link\":\"/reference/http-api\"}]}]},\"locales\":{},\"scrollOffset\":134,\"cleanUrls\":false}");</script>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><h2 id="hooks-vs-channels-vs-evals" tabindex="-1">Hooks vs channels vs evals <a class="header-anchor" href="#hooks-vs-channels-vs-evals" aria-label="Permalink to &quot;Hooks vs channels vs evals&quot;">​</a></h2><p>All three consume the same stream, for different jobs:</p><table tabindex="0"><thead><tr><th></th><th>Hooks</th><th>Channel <code>events</code></th><th>Evals</th></tr></thead><tbody><tr><td>Scope</td><td>every session of the agent</td><td>sessions the channel owns</td><td>one test turn</td></tr><tr><td>Job</td><td>observe: audit, metrics, mirrors, derived state</td><td>deliver: replies back to the channel&#39;s surface</td><td>assert: gates over the trajectory</td></tr><tr><td>Context</td><td><code>ctx.host</code>, <code>ctx.artifacts</code>, session info</td><td><code>channel.state</code>, <code>setContinuationToken</code>, <code>ctx.host</code>, session info</td><td>the <code>t</code> assertion helpers</td></tr><tr><td>Can affect the run</td><td>no</td><td>yes, it owns the surface</td><td>n/a</td></tr><tr><td>Authored at</td><td><code>bot/hooks/*.ts</code></td><td>channel config</td><td><code>evals/**/*.eval.ts</code></td></tr></tbody></table><h2 id="hook-boundaries" tabindex="-1">Hook boundaries <a class="header-anchor" href="#hook-boundaries" aria-label="Permalink to &quot;Hook boundaries&quot;">​</a></h2><table tabindex="0"><thead><tr><th>You want to</th><th>Use instead</th></tr></thead><tbody><tr><td>Add context before the model runs</td><td>The channel&#39;s <code>send</code> message and <code>workspaceFiles</code>, <code>instructions.md</code>, skills, or <code>sandbox/workspace/</code> seed files</td></tr><tr><td>Reply on Slack, comment on a PR, or post any other delivery</td><td>The channel&#39;s <code>events</code> map, or the Slack and GitHub packs</td></tr><tr><td>Show PR progress (merge-box check, sticky banner)</td><td><code>githubChannel({ progress: { commitStatus, banner } })</code>; see <a href="./../guides/github.html">GitHub agents</a></td></tr><tr><td>Block, approve, or rewrite a tool call</td><td><a href="./tools.html#gate-a-tool-on-human-approval"><code>needsApproval</code></a> on the tool</td></tr><tr><td>Act on the final assistant text, reject it for a same-turn repair, or fail a bad turn</td><td><code>defineResult</code></td></tr><tr><td>Gate a change on behavior</td><td><a href="./../evals.html">Evals</a></td></tr></tbody></table><h2 id="test-a-hook" tabindex="-1">Test a hook <a class="header-anchor" href="#test-a-hook" aria-label="Permalink to &quot;Test a hook&quot;">​</a></h2><p>A hook definition is a plain object, so a unit test calls <code>hook.events[&quot;turn.completed&quot;]</code> directly with an event and a stub <code>HookContext</code>. Discovery skips <code>*.test.ts</code>, so the test can live next to the hook.</p><table tabindex="0"><thead><tr><th>Command</th><th>What it reports</th></tr></thead><tbody><tr><td><code>bdk validate --dir .</code></td><td>Discovery errors and the empty-handlers warning</td></tr><tr><td><code>bdk info --dir . --json</code></td><td>Loaded hooks under <code>agents[].hooks</code></td></tr><tr><td><code>bdk run --dir . --message &quot;…&quot;</code></td><td>Serve log on stderr, including <code>hook &quot;&lt;name&gt;&quot; handler for &lt;event&gt; threw: …</code></td></tr></tbody></table><p>On hosting, read the same log with <a href="./cli.html#logs"><code>bdk logs</code></a>.</p><h2 id="related" tabindex="-1">Related <a class="header-anchor" href="#related" aria-label="Permalink to &quot;Related&quot;">​</a></h2><ul><li><a href="./../guides/hooks.html">Hooks guide</a>: meter usage and page on failure</li><li><a href="./sessions.html">Sessions and streaming</a>: the event vocabulary hooks observe</li><li><a href="./../guides/opentelemetry.html">OpenTelemetry</a>: OTLP traces and metrics from the same event stream</li><li><a href="./../deployment.html#observability">Deployment</a>: runtime logs and export paths</li><li><a href="./channels.html#events">Channels</a>: the delivery-side counterpart</li></ul></div></div></main><footer class="VPDocFooter" data-v-4e7466dc data-v-5e6607d6><!--[--><!--]--><!----><nav class="prev-next" aria-labelledby="doc-footer-aria-label" data-v-5e6607d6><span class="visually-hidden" id="doc-footer-aria-label" data-v-5e6607d6>Pager</span><div class="pager" data-v-5e6607d6><a class="VPLink link pager-link prev" href="/docs/reference/schedules.html" data-v-5e6607d6><!--[--><span class="desc" data-v-5e6607d6>Previous page</span><span class="title" data-v-5e6607d6>Schedules & reminders</span><!--]--></a></div><div class="pager" data-v-5e6607d6><a class="VPLink link pager-link next" href="/docs/reference/evals.html" data-v-5e6607d6><!--[--><span class="desc" data-v-5e6607d6>Next page</span><span class="title" data-v-5e6607d6>Evals</span><!--]--></a></div></nav></footer><!--[--><!--]--></div></div></div><!--[--><!--]--></div></div><!----><!--[--><!--]--></div></div>
+    <script>window.__VP_HASH_MAP__=JSON.parse("{\"building-with-agents.md\":\"Df87rAe1\",\"deployment.md\":\"BYuEcDBv\",\"evals.md\":\"C851kViu\",\"guides_agent-to-agent.md\":\"Cps5NiCV\",\"guides_bitbucket.md\":\"CKUayYtD\",\"guides_cloud-agents.md\":\"CWJjS9No\",\"guides_convert-automation.md\":\"DMEX9nF-\",\"guides_github.md\":\"TuNiZAOQ\",\"guides_gitlab.md\":\"CtNI4fSH\",\"guides_grokbot-agents.md\":\"tD1smFhU\",\"guides_hooks.md\":\"5Ce3NXxZ\",\"guides_improve.md\":\"CRrYq22s\",\"guides_jev.md\":\"D7XH4JH3\",\"guides_mcp-oauth.md\":\"DR3zhC9r\",\"guides_migrate.md\":\"sCAvvlC6\",\"guides_opentelemetry.md\":\"jcPNrQbH\",\"guides_slack.md\":\"Bn-WupSE\",\"guides_webhooks.md\":\"BBvAm_VF\",\"hillclimbing.md\":\"Dxvd-0gT\",\"index.md\":\"Dxxr7pFa\",\"quickstart.md\":\"BK5gjHM2\",\"reference_agent-config.md\":\"DrtLxWgR\",\"reference_artifacts.md\":\"DLV9MZES\",\"reference_channels.md\":\"LbNIJBwd\",\"reference_cli.md\":\"dYCAL2lB\",\"reference_connections.md\":\"DLrgAd5f\",\"reference_evals.md\":\"D5i8PuXJ\",\"reference_extensions.md\":\"OUacPetl\",\"reference_hooks.md\":\"B-eGa2km\",\"reference_http-api.md\":\"DbFNOubV\",\"reference_instructions.md\":\"DrcHZXig\",\"reference_playground.md\":\"1hx0gcIu\",\"reference_project-layout.md\":\"C2JMRh7p\",\"reference_prompt.md\":\"DqPh71XN\",\"reference_schedules.md\":\"BuJ8fgMa\",\"reference_sessions.md\":\"CyM7ARz1\",\"reference_skills.md\":\"ClkMoQsV\",\"reference_subagents.md\":\"gmPt5J-M\",\"reference_tools.md\":\"DzIY9JzY\",\"templates_agentic-owners.md\":\"CvmABtia\",\"templates_grokbot-agents.md\":\"2sydjFiO\",\"templates_security-reviewer.md\":\"Gh6EF9Us\",\"templates_thermo-quality-review.md\":\"B77UyTrX\",\"templates_thermo-review.md\":\"DRJ7mC5U\",\"templates_triage.md\":\"CNN6b0JZ\",\"troubleshooting.md\":\"x-GBa7wN\"}");window.__VP_SITE_DATA__=JSON.parse("{\"lang\":\"en-US\",\"dir\":\"ltr\",\"title\":\"Grok Bot Development Kit (BDK)\",\"description\":\"Build and serve bots and agents from versioned Markdown and TypeScript.\",\"base\":\"/docs/\",\"head\":[],\"router\":{\"prefetchLinks\":true},\"appearance\":true,\"themeConfig\":{\"sdkVersion\":\"0.2.12\",\"nav\":[{\"text\":\"Quickstart\",\"link\":\"/quickstart\"},{\"text\":\"Guides\",\"link\":\"/guides/mcp-oauth\"},{\"text\":\"Integrations\",\"link\":\"/guides/github\"},{\"text\":\"Templates\",\"link\":\"/templates/security-reviewer\"},{\"text\":\"Reference\",\"link\":\"/reference/project-layout\"}],\"search\":{\"provider\":\"local\"},\"outline\":{\"level\":[2,3]},\"sidebar\":[{\"text\":\"Getting started\",\"items\":[{\"text\":\"Overview\",\"link\":\"/\"},{\"text\":\"Building your first agent\",\"link\":\"/quickstart\"}]},{\"text\":\"Integrations\",\"collapsed\":false,\"items\":[{\"text\":\"GitHub\",\"link\":\"/guides/github\"},{\"text\":\"Slack\",\"link\":\"/guides/slack\"},{\"text\":\"Webhooks\",\"link\":\"/guides/webhooks\"},{\"text\":\"Cursor Automations\",\"link\":\"/guides/convert-automation\"},{\"text\":\"OpenTelemetry\",\"link\":\"/guides/opentelemetry\"},{\"text\":\"GitLab\",\"link\":\"/guides/gitlab\"},{\"text\":\"Bitbucket\",\"link\":\"/guides/bitbucket\"}]},{\"text\":\"Extensions\",\"collapsed\":false,\"items\":[{\"text\":\"Overview\",\"link\":\"/reference/extensions\"},{\"text\":\"Cloud agents\",\"link\":\"/guides/cloud-agents\"},{\"text\":\"Grok Bot agents\",\"link\":\"/guides/grokbot-agents\"},{\"text\":\"Self-improvement\",\"link\":\"/guides/improve\"},{\"text\":\"Jev\",\"link\":\"/guides/jev\"}]},{\"text\":\"Guides\",\"collapsed\":false,\"items\":[{\"text\":\"MCP\",\"link\":\"/guides/mcp-oauth\"},{\"text\":\"Hooks\",\"link\":\"/guides/hooks\"},{\"text\":\"Peer agents\",\"link\":\"/guides/agent-to-agent\"},{\"text\":\"Deployment\",\"link\":\"/deployment\"},{\"text\":\"Early-alpha migration\",\"link\":\"/guides/migrate\"},{\"text\":\"Evals\",\"link\":\"/evals\"},{\"text\":\"Hillclimbing\",\"link\":\"/hillclimbing\"},{\"text\":\"Build with a coding agent\",\"link\":\"/building-with-agents\"},{\"text\":\"Troubleshooting\",\"link\":\"/troubleshooting\"}]},{\"text\":\"Templates\",\"collapsed\":false,\"items\":[{\"text\":\"Grok Bot agents\",\"link\":\"/templates/grokbot-agents\"},{\"text\":\"Security reviewer\",\"link\":\"/templates/security-reviewer\"},{\"text\":\"Thermo review\",\"link\":\"/templates/thermo-review\"},{\"text\":\"Thermo quality review\",\"link\":\"/templates/thermo-quality-review\"},{\"text\":\"Agentic Approver\",\"link\":\"/templates/agentic-owners\"},{\"text\":\"Triage agent\",\"link\":\"/templates/triage\"}]},{\"text\":\"Reference\",\"collapsed\":false,\"items\":[{\"text\":\"Project layout\",\"link\":\"/reference/project-layout\"},{\"text\":\"Agent config\",\"link\":\"/reference/agent-config\"},{\"text\":\"Instructions\",\"link\":\"/reference/instructions\"},{\"text\":\"Tools\",\"link\":\"/reference/tools\"},{\"text\":\"prompt\",\"link\":\"/reference/prompt\"},{\"text\":\"Skills\",\"link\":\"/reference/skills\"},{\"text\":\"MCP Connections\",\"link\":\"/reference/connections\"},{\"text\":\"Subagents\",\"link\":\"/reference/subagents\"},{\"text\":\"Channels\",\"link\":\"/reference/channels\"},{\"text\":\"Schedules & reminders\",\"link\":\"/reference/schedules\"},{\"text\":\"Hooks\",\"link\":\"/reference/hooks\"},{\"text\":\"Evals\",\"link\":\"/reference/evals\"},{\"text\":\"Artifacts\",\"link\":\"/reference/artifacts\"},{\"text\":\"Sessions & streaming\",\"link\":\"/reference/sessions\"},{\"text\":\"Playground\",\"link\":\"/reference/playground\"},{\"text\":\"CLI\",\"link\":\"/reference/cli\"},{\"text\":\"HTTP API\",\"link\":\"/reference/http-api\"}]}]},\"locales\":{},\"scrollOffset\":134,\"cleanUrls\":false}");</script>
     
   </body>
 </html>

package/dist/docs/reference/hooks.md

@@ -73,6 +73,7 @@ want the final text; `message.completed` already has it.
 | `actions.requested` | `{ calls: [{ callId, toolName, args?, parentCallId? }], parentCallId? }`. One envelope per model step once that step has listed its tools. A single tool is a batch of one. `parentCallId` marks subagent work |
 | `actions.completed`    | `{ results: [{ callId, toolName, output?, isError, stubbed?, parentCallId? }], parentCallId? }`. Pair with `actions.requested`; emitted when every call in that batch has a result                          |
 | `action.result`     | `{ callId, toolName, output?, isError, stubbed?, parentCallId? }`. Live per-call envelope for chips and spans. `stubbed` means a dry-run session answered a write without running it                         |
+| `action.tool_retry` | `{ callId, toolName, attempt, reason, connection? }`. A read is running again after a transient failure. `attempt` is the try about to run. `reason` is a class such as `transport` or `http_503` |
 
 The types are `SessionEvent`, `SessionEventType`, and `HookContext`,
 exported from `@cursor/bdk`.