Author or wire a new hook emission in Nova's LangChain agent loop. Use when adding observability for a new tool, when promoting a logged audit event to a structured receipt, or when extending the agent's self-evaluation storage. Nova's hook surface today is `RunJournal` (`backend/packages/harness/deerflow/runtime/journal.py:38`) which implements `BaseCallbackHandler` (on_tool_start / on_tool_end / on_chain_start / on_chain_end); there is no separate `PreToolUse`/`PostToolUse` enum, so any new hook emission must go through `RunJournal.record_middleware` or a new `BaseCallbackHandler` subclass. Triggers on phrases like "add observability for X", "log when tool Y runs", "instrument Z", or before shipping any new middleware.
التثبيت
التثبيت باستخدام Codex أو Claude انسخ هذا Prompt والصقه في Codex أو Claude أو مساعد آخر ليراجع صفحة Skill ويثبّتها لك.
Author or wire a new hook emission in Nova's LangChain agent loop. Use when adding observability for a new tool, when promoting a logged audit event to a structured receipt, or when extending the agent's self-evaluation storage. Nova's hook surface today is `RunJournal` (`backend/packages/harness/deerflow/runtime/journal.py:38`) which implements `BaseCallbackHandler` (on_tool_start / on_tool_end / on_chain_start / on_chain_end); there is no separate `PreToolUse`/`PostToolUse` enum, so any new hook emission must go through `RunJournal.record_middleware` or a new `BaseCallbackHandler` subclass. Triggers on phrases like "add observability for X", "log when tool Y runs", "instrument Z", or before shipping any new middleware.
Identify the event class. Is it a tool.start / tool.end / chain.start / chain.end (use BaseCallbackHandler)? Or a domain event that needs its own handler (define a new BaseCallbackHandler subclass and wire it in worker.py:235)?
If a LangChain hook: extend RunJournal in backend/packages/harness/deerflow/runtime/journal.py. Add a method like _record_tool_event(tool_name, tool_call_id, payload) that writes a RunEvent to the store.
If a domain event: add a new BaseCallbackHandler subclass (see subagents/token_collector.py:16 for the shape). Register it in worker.py:235 alongside journal.
Wire SSE emission so the frontend can consume the event in real time. Add the event type to core/threads/hooks.ts:onCustomEvent (currently recognises task_running, llm_retry, task_progress, verify_result, llm_error).
Update the frontend consumer. Add the new event type to the switch in core/threads/hooks.ts:859-960; route the payload into a new tab in the Agent's Computer panel; if a MetricCounter is appropriate, add a pill in runtime-capabilities-bar.tsx.
Test contract
Unit:backend/tests/test_journal.py should grow a test that calls the new hook emission with a sample payload and asserts the right RunEvent is written.
Replay-golden: the SSE event shape contract (backend/tests/_replay_fixture.py:113) must include the new event in write_read_file.ultra.events.json if the agent graph exercises the new event path during the recorded scenario.
Frontend:frontend/tests/unit/core/threads/hooks-*.test.ts should add a parser test for the new event.
Anti-patterns (read before authoring)
❌ Don't add a new record_middleware call — the function exists but is dead. If you must log, log via RunJournal._record_* methods.
❌ Don't patch langgraph middleware event signatures — that's an upstream contract; instead, expose a new BaseCallbackHandler that observes the existing events.
❌ Don't add an asyncio.Queue listener per event type — use the existing RunEventStore so the event flow is replayable.
❌ Don't write to stdout / stderr in a hook — use logger.debug or push to RunEventStore. stdout breaks the test capture path.
