| 1 | # Python Function Extensions DOX |
| 2 | |
| 3 | ## Purpose |
| 4 | |
| 5 | - Own implicit `@extensible` backend hook implementations. |
| 6 | - Preserve nested module, class/function, method, and `start`/`end` extension layout. |
| 7 | |
| 8 | ## Ownership |
| 9 | |
| 10 | - Each nested path mirrors a Python module and qualname segment. |
| 11 | - Leaf `start/` and `end/` directories own ordered extension files for that extensible function point. |
| 12 | |
| 13 | ## Local Contracts |
| 14 | |
| 15 | - Do not flatten nested qualname paths into retired legacy folder names. |
| 16 | - Extension functions must match the implicit hook's supplied arguments. |
| 17 | - Preserve ordering prefixes where exception handling, watchdog registration, or cleanup depends on them. |
| 18 | - Hooks that mirror persisted AI responses into UI logs must reuse existing stream log items and avoid duplicating live response-tool logs. |
| 19 | - The `AgentContext.run_task/end` hook attaches integration callbacks to the returned `DeferredTask`; keep terminal side effects out of `agent.py`. |
| 20 | - Recovery-loop circuit breakers must stop at the General Settings limit and render their user-visible cost warning from a core framework prompt. |
| 21 | - Prompt settings snapshots must be task-local, accessed through `get_settings_for_prompt()`, and end with the matching `Agent.prepare_prompt` call, including exceptional exits. |
| 22 | |
| 23 | ## Work Guidance |
| 24 | |
| 25 | - Keep implicit hook extensions narrow and colocated with the exact function point they extend. |
| 26 | |
| 27 | ## Verification |
| 28 | |
| 29 | - Run targeted tests for the affected function point after changes. |
| 30 | |
| 31 | ## Child DOX Index |
| 32 | |
| 33 | No child DOX files. |