feat: Universal Hooks and Policy System for Hedera Agent Kit

README.md

@@ -11,6 +11,7 @@
 - [Key Features](#key-features)
 - [About the Agent Kit Functionality](#agent-kit-functionality)
 - [Third Party Plugins](#third-party-plugins)
+- [Hooks and Policies](#hooks-and-policies)
 - [Developer Examples](#developer-examples)
 - [🚀 60-Second Quick-Start](#-60-second-quick-start)
 - [Agent Execution Modes](#agent-execution-modes)
@@ -72,10 +73,28 @@ The Hedera Agent Kit is extensible with third party plugins by other projects. S
   Github repository: [https://github.com/henrytongv/chainlink-price-plugin-js](https://github.com/henrytongv/chainlink-price-plugin-js). Tested/endorsed version of plugin: chainlink-pricefeed-plugin@1.0.4
 
 _[Contribute your own plugin](https://github.com/hashgraph/hedera-agent-kit-js/blob/main/docs/PLUGINS.md)_
+
+### Hooks and Policies
+
+The Hedera Agent Kit provides a flexible and powerful system for putting limits on tool usage and enforcing business logic, effectively enabling you to limit the functionality of AI agents through **Hooks** and **Policies**. These hooks and policies can be used to enforce security, compliance, and other business rules.
+
+**Features**
+* Hooks and policies can be called when parameters are passed, after parameter normalization, before tool execution when a transaction has been formed, and after tool execution when a transaction has been signed and submitted.
+* Users can create their own hooks and policies on any available Hedera Agent Kit tool, simply fork this repo and create your own hooks and policies in the `typescript/src/hooks` and `typescript/src/policies` directories.
+* We have provided examples:
+  * A hook to [log actions to an HCS topic](https://github.com/hashgraph/hedera-agent-kit-js/blob/main/docs/HOOKS_AND_POLICIES.md#1-hcsaudittrailhook-hook), creating an easy to track audit trail. 
+  * A policy that [sets the maximum number of recipients](https://github.com/hashgraph/hedera-agent-kit-js/blob/main/docs/HOOKS_AND_POLICIES.md#2-maxrecipientspolicy-policy) in a transfer or airdrop.
+  * A policy the [blocks tool usage](https://github.com/hashgraph/hedera-agent-kit-js/blob/main/docs/HOOKS_AND_POLICIES.md#3-rejecttoolpolicy-policy) by an agent.
+
+For more information on hooks and policies, see the [Hooks and Policies documentation](https://github.com/hashgraph/hedera-agent-kit-js/blob/main/docs/HOOKS_AND_POLICIES.md).
+
+Try out an example [Audit Hook Agent](https://github.com/hashgraph/hedera-agent-kit-js/blob/main/docs/DEVEXAMPLES.md#option-i-try-out-the-audit-hook-agent) to see how hooks and policies work in practice.
+
 ---
 
 ## Developer Examples
 
+
 You can try out examples of the different types of agents you can build by followin the instructions in the [Developer Examples](https://github.com/hashgraph/hedera-agent-kit-js/blob/main/docs/DEVEXAMPLES.md) doc in this repo.
 
 First follow instructions in the [Developer Examples to clone and configure the example](https://github.com/hashgraph/hedera-agent-kit-js/blob/main/docs/DEVEXAMPLES.md), then choose from one of the examples to run:
@@ -289,15 +308,15 @@ Currently, the following plugins are available:
 - Get Account Token Balances Query
 - Get Topic Messages Query
 
-_See more in [docs/PLUGINS.md](https://github.com/hashgraph/hedera-agent-kit-js/blob/main/docs/PLUGINS.md)_
+_See more in [docs/PLUGINS.md](docs/PLUGINS.md)_
 
 ---
 
 ## Creating Plugins & Contributing
 
-- You can find a guide for creating plugins in [docs/PLUGINS.md](https://github.com/hashgraph/hedera-agent-kit-js/blob/main/docs/PLUGINS.md)
+- You can find a guide for creating plugins in [docs/PLUGINS.md](docs/PLUGINS.md)
 
-- This guide also has instructions for [publishing and registering your plugin](https://github.com/hashgraph/hedera-agent-kit-js/blob/main/docs/PLUGINS.md#publish-and-register-your-plugin) to help our community find and use it.
+- This guide also has instructions for [publishing and registering your plugin](docs/PLUGINS.md#publish-and-register-your-plugin) to help our community find and use it.
 
 - If you would like to contribute and suggest improvements for the cord SDK and MCP server, see [CONTRIBUTING.md](https://github.com/hashgraph/hedera-agent-kit-js/blob/main/CONTRIBUTING.md) for details on how to contribute to the Hedera Agent Kit.
 

docs/DEVEXAMPLES.md

@@ -39,23 +39,36 @@ ACCOUNT_ID= 0.0.xxxxx
 PRIVATE_KEY= 302e...
 OPENAI_API_KEY= sk-proj-...
 ```
+
+##### About Private Keys
+
+Hedera supports both **ECDSA** and **ED25519** private keys. The examples use **ECDSA** by default. To use an **ED25519** key, uncomment the appropriate line in the agent's `.ts` file:
+
+```ts
+// PrivateKey.fromStringED25519(process.env.PRIVATE_KEY!)
+```
+
+For more information about Hedera key types and formats, see the [Hedera documentation on Keys and Signatures](https://docs.hedera.com/hedera/core-concepts/keys-and-signatures#key-types:-ecdsa-vs-ed25519).
+
 > Create similar .env files for each of the other framework examples
 
 ### 3 – Choose an Example
 Try out one or more of the example agents:
 
 * **Option A -** [Example Tool Calling Agent](#option-a-run-the-example-tool-calling-agent)
-* **Option B -** [Example Structured Chat Agent](#option-b-run-the-structured-chat-agent)
+* **Option B -** [Example Structured Chat Agent](#option-b-run-the-structured-chat-agent-langchain-v03-only)
 * **Option C -** [Example Return Bytes Agent](#option-c-try-the-human-in-the-loop-chat-agent)
 * **Option D -** [Example MCP Server](#option-d-try-out-the-mcp-server)
 * **Option E -** [Example External MCP Agent](#option-e-try-out-the-external-mcp-agent)
 * **Option F -** [Example ElizaOS Agent](#option-f-try-out-the-hedera-agent-kit-with-elizaos)
 * **Option G -** [Example Preconfigured MCP Client Agent](#option-g-try-out-the-preconfigured-mcp-client-agent)
+* **Option H -** [Example Policy Enforcement Agent](#option-h-run-the-policy-enforcement-agent)
+* **Option I -** [Example Audit Trail Agent](#option-i-run-the-audit-trail-agent)
 
 <!-- OR
 Try out the create-hedera-app CLI tool to create a new Hedera Agent and a front end application -->
 
-### Option A: Run the Example Tool Calling Agent 
+### Option A: Run the Example Tool Calling Agent
 With the tool-calling-agent you can experiment with and call the [available tools](../docs/HEDERAPLUGINS.md) in the Hedera Agent Kit for the operator account (the account you are using in the .env file). This example tool-calling-agent uses GPT 4-o-mini that is a simple template you can use with other LLMs. This agent is intended for use with simple tasks, such as an individual tool call.
 
 #### LangChain Classic
@@ -285,7 +298,7 @@ PRIVATE_KEY=302e...
 OPENAI_API_KEY=sk-proj-...
 ```
 
-**Note about private keys:** The Hedera Agent Kit supports DER-encoded private keys by default (e.g., `302e...`). If you have a hex-encoded key, uncomment the appropriate line in `external-mcp-agent.ts` to use `PrivateKey.fromStringED25519()` instead. Learn more about [Hedera key types](https://docs.hedera.com/hedera/core-concepts/keys-and-signatures#key-types:-ecdsa-vs-ed25519).
+**Note about private keys:** The Hedera Agent Kit supports both **ECDSA** and **ED25519** private keys. The examples use **ECDSA** by default (e.g., `302e...`). If you have an **ED25519** key, uncomment the appropriate line in `external-mcp-agent.ts` to use `PrivateKey.fromStringED25519()` instead. Learn more about [Hedera key types](https://docs.hedera.com/hedera/core-concepts/keys-and-signatures#key-types:-ecdsa-vs-ed25519).
 
 3. Update the MCP server path in `external-mcp-agent.ts` in the `args` array with the absolute path to your built MCP server.
 
@@ -381,4 +394,62 @@ npm run ai-sdk:preconfigured-mcp-client-agent
 These agents connect to the configured MCP servers (defined in your code) and allow you to interact with the provided tools using natural language.
 
 > If using `HederaMCPServer.HGRAPH_MCP_MAINNET`, ensure you have set the `HGRAPH_API_KEY` in your `.env` file. See [docs.hgraph.com](https://docs.hgraph.com/mcp-server/setup-claude) for details.
-> 
+
+### Option H: Run the Policy Enforcement Agent
+
+This example demonstrates how to use the **MaxRecipientsPolicy** to enforce rules on transactions. In this case, it restricts any HBAR transfer to a maximum of 2 recipients.
+
+**Found at:**
+- `typescript/examples/ai-sdk/policy-enforcement-agent.ts`
+- `typescript/examples/langchain-v1/policy-enforcement-agent.ts`
+
+#### Running the Example
+
+##### AI SDK
+
+```bash
+cd typescript/examples/ai-sdk
+npm install
+npm run ai-sdk:policy-enforcement-agent
+```
+
+##### LangChain v1
+
+```bash
+cd typescript/examples/langchain-v1
+npm install
+npm run langchain:policy-enforcement-agent
+```
+
+---
+
+### Option I: Run the Audit Trail Agent
+
+This example demonstrates how to use the **HcsAuditTrailHook** to automatically audit specific actions (like HBAR transfers or token creation) by submitting audit logs to a Hedera Consensus Service (HCS) topic.
+
+**Found at:**
+- `typescript/examples/ai-sdk/audit-trail-agent.ts`
+- `typescript/examples/langchain-v1/audit-trail-agent.ts`
+
+> [!IMPORTANT]
+> This agent works only in `mode: AgentMode.AUTONOMOUS`.
+
+#### Running the Example
+
+##### AI SDK
+
+```bash
+cd typescript/examples/ai-sdk
+npm install
+npm run ai-sdk:audit-trail-agent
+```
+
+##### LangChain v1
+
+```bash
+cd typescript/examples/langchain-v1
+npm install
+npm run langchain:audit-trail-agent
+```
+
+---