@devries-cameron20 / composio Mirror · read-only / commits / 9a4977f79
Fork 0

Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.

Mirrored from https://github.com/Camo67/composio.git

Synced Nov 21, 08:30 UTC

feat(core): add session hooks to TS and Python sessions (#4958)

## Summary Tool Router sessions now have hooks ([ComposioHQ/platform#14000](https://github.com/ComposioHQ/platform/pull/14000), merged and on staging). A hook can block a tool call before it runs, or block its result before the agent sees it. The API answers a blocked call with a new `result_type: "blocked"`. Today both SDKs reject an unknown `result_type` with a `ValidationError`, so an agent on a hooked session crashes instead of being told why. This PR lets both SDKs set hooks and read blocked results. Designated PR reviewer: [@jkomyno](mailto:alberto@composio.dev). ## Changes - `create()` and `update()` accept `hooks` (TS camelCase, Python snake_case). On `update()`, `hooks` replaces the list and `null` / `None` removes every hook. TS rejects `hooks` together with `experimental.sessionConfigId`. ```ts hooks: [{ type: 'before_execute', id: 'no_external_email', name: 'No external email', appliesTo: { toolkits: ['gmail'] }, handler: { type: 'condition_check', condition: 'Sending email to anyone outside example.org', action: 'block' }, }] ``` - `session.execute()` / `executeMeta()` return a blocked call as a result, not an error. Provider integrations hand it to the agent as a failed call with the hook's message. ```ts { resultType: 'blocked', data: {}, error: 'Blocked by session policy: No external email', logId: '', blockReason: { type: 'request_blocked', hookId: 'no_external_email' }, hookResults: [{ id: 'no_external_email', status: 'evaluated', outcome: 'block' }] } ``` - `session.proxyExecute()` and `ctx.proxyExecute()` now return a union: `{ resultType: 'completed', status, data, headers, ... }` or `{ resultType: 'blocked', blockReason, message, hookResults }`. - Every result carries `hookResults` when a hook applied. A hook that couldn't be evaluated shows as `{ id, status: 'unavailable' }` and doesn't block: the call returns its normal result. A response-blocked call keeps its `logId` and `instantCharge`, since the tool ran. - The generated clients don't type `hooks` or `blocked` yet, so the SDK sends `hooks` as an extra body field and parses `blocked` with its own schemas (zod in TS, pydantic in Python). Both keep working once the clients are regenerated after the platform PR. ## Type of change - [ ] Bug fix - [x] New feature - [ ] Refactor/Chore - [ ] Documentation - [x] Breaking change `proxyExecute()`'s return type is now a union, so TS code that reads `status` without checking `resultType` first no longer compiles. The `tool-router` example is updated for this. Nothing changes at runtime for sessions without hooks. ## How Has This Been Tested? - TS: `pnpm typecheck`, `pnpm --filter @composio/core test` (1,939 passed). New `sessionHooksExecution.test.ts` runs a real client over a stubbed `fetch`, covering every execute and proxy path. - Python: `pytest tests` (2,341 passed), ruff, and mypy on `composio` and the changed tests. New `TestSessionHooks` covers create/update and every execute and proxy path over a stub transport. ## Checklist - [ ] I have read the Code of Conduct and this PR adheres to it - [ ] I have read and understand every line of this diff, including any LLM-generated code - [x] Any third-party docs links or promotional content follow the [third-party links policy](https://github.com/ComposioHQ/composio/blob/next/CONTRIBUTING.md#third-party-links-in-docs) - [x] I ran linters/tests locally and they passed - [ ] I updated documentation as needed - [x] I added tests or explain why not applicable - [x] I added a changeset if this change affects published packages ## Additional context The platform side is merged and on staging. The generated clients pick up the new spec on their next spec sync; this PR doesn't depend on that. Docs follow separately. 🤖 Generated with [Claude Code](https://claude.com/claude-code)

mukund-composio committed Oct 22, 2026 at 12:36 UTC 9a4977f79d9f67d59e7c6d160c24927df471c295

No changes.