agentic-cli 0.5.2__tar.gz → 0.5.3__tar.gz

{agentic_cli-0.5.2 → agentic_cli-0.5.3}/CHANGELOG.md

@@ -5,6 +5,39 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+## [0.5.3] - 2026-06-14
+
+### Added
+- **Session fact extraction now runs on exit** (`auto_extract_session_facts`): `BaseWorkflowManager.on_session_end()` is invoked from the CLI shutdown path (`BaseCLIApp._extract_session_facts_on_exit`), extracting key facts/preferences from the conversation into memory. Previously the hook had no call site. `on_session_end()` now also sources the session messages itself (from the live backend session) when called with no arguments; it remains a safe no-op without a memory store, and never blocks shutdown.
+
+### Removed
+- **Tool Reflection Store removed** (`save_reflection` tool, `ReflectionStore`, `REFLECTION_STORE`, and the `enable_tool_reflections` setting). Introduced in v0.5.0 as a "cross-session learning primitive," it shipped only as a standalone store + tool — the planned injection and session-end wiring were never completed, so it was inert from v0.5.0 through v0.5.2 (the v0.5.0 changelog's "wired via session-end hook" was inaccurate). The design also conflated mechanical failure-capture with LLM heuristic synthesis in a single opportunistic tool the model had to remember to call. Removed rather than finished; tool-failure heuristics, if wanted later, are better served by automatic capture + session-end synthesis (mirroring `auto_extract_session_facts`) or by tagged entries in the existing memory store.
+
+### Security
+- **`grep` ripgrep argument injection fixed** (`tools/grep_tool.py`): the LLM-supplied `pattern` was passed to ripgrep as a bare positional, so a value like `--pre=<cmd>` was parsed as a flag and could run an arbitrary program per searched file — remote code execution holding only `filesystem.read`. The pattern is now passed via `-e` and option parsing is terminated with `--` before the path, so neither can be interpreted as a flag.
+- **`execute_python` library escape closed** (`tools/executor.py`): the AST/name allow-list cannot neutralize `numpy`/`pandas`/`scipy`/`sklearn`/`matplotlib`, which re-expose file, network, and pickle I/O through public APIs (e.g. `numpy.DataSource().open()`, `pandas.read_pickle(url)`) — an escape from the in-process restrictions (arbitrary file read, pickle-based code execution) when no OS sandbox is active. These `SANDBOXED_MODULES` are now importable **only when `os_sandbox_enabled=True`**; without it, only the pure-computation `CORE_MODULES` are available. The class docstring now states that the AST validation is defense-in-depth, not a security boundary.
+- **arXiv PDF download SSRF fixed** (`tools/arxiv_source.py`): `download_pdf` issued a raw `httpx.get(follow_redirects=True)` with no URL validation or size cap on a `pdf_url` taken from a remote Atom feed — bypassing the hardened `ContentFetcher`. It now routes through `get_or_create_fetcher().fetch()`, inheriting SSRF validation (private-IP/redirect blocking), DNS-rebinding checks, and the byte cap. The arXiv API endpoints were also switched from plaintext HTTP to HTTPS to remove the on-path feed-rewrite vector.
+
+### Changed
+- **`execute_python` no longer exposes `numpy`/`pandas` (etc.) by default.** Enabling them requires `os_sandbox_enabled=True` (with `sandbox-exec` on macOS or `bwrap` on Linux). This is a deliberate, user-visible reduction of the default capability surface.
+
+### Fixed
+- **ADK session resume was a silent no-op** (`workflow/adk/manager.py`): `_inject_session_messages` appended events to the copy returned by `create_session`, so the stored session stayed empty and "Session resumed" restored nothing on the ADK backend. Now uses `append_event` with real `google.adk.events.Event` objects so events land in the stored session.
+- **Corrupt sessions index no longer hides every session** (`persistence/session.py`): a corrupt or non-dict `_sessions_index.json` read as empty, so the next save reset it to a single entry and all other sessions vanished from `list_sessions()`. The index now rebuilds from the session files on any parse/shape error (and a non-dict payload no longer raises `AttributeError`).
+- **`MemoryStore` is now thread-safe** (`tools/memory_tools.py`): added a lock around `store`/`update`/`delete`/`search` and the full-file `_save` (note `search` is a writer — it bumps access counters). Prevents "dictionary changed size during iteration" and lost writes when LangGraph's `ToolNode` runs tools concurrently in executor threads.
+- **Atomic writes are now durable** (`file_utils.py::_atomic_write`): fsync before the rename (so a crash can't persist the rename ahead of the data and destroy the previously-good file), a unique temp filename (two concurrent writers no longer truncate a shared `.tmp`), and explicit UTF-8 (no locale-dependent `UnicodeEncodeError`). Applies to all persistence consumers (settings, sessions, memory).
+- **LangGraph graph construction was completely broken** (`workflow/langgraph/graph_builder.py`): `build()` called the local `_get_tools(config)` helper in the agent-node loop before it was defined further down the function, so Python treated `_get_tools` as an unbound local and every graph build raised `UnboundLocalError`. The helper (and `_overrides`) are now defined before first use. This went unnoticed because the dev env had no `langgraph` installed, so the build tests were skipped.
+- **LangGraph sqlite/postgres checkpointers were nonfunctional** (`workflow/langgraph/persistence/checkpointers.py`): `create_checkpointer` returned `SqliteSaver/PostgresSaver.from_conn_string(...)` directly, but in current `langgraph-checkpoint-*` that is a context manager (not a saver), and the sync savers can't serve the async `astream_events` path. `create_checkpointer` is now async and uses the async savers (`AsyncSqliteSaver`/`AsyncPostgresSaver`): it enters the connection context, calls `setup()`, and returns `(saver, context_manager)`; `LangGraphWorkflowManager` closes the context manager in `cleanup()`. The `langgraph` extra now also pulls `langgraph-checkpoint-sqlite`/`-postgres`.
+- **LangGraph node `retry` deprecation** (`workflow/langgraph/graph_builder.py`): `graph.add_node(..., retry=...)` updated to `retry_policy=...` (`retry` is deprecated since LangGraph 0.5, removed in 2.0).
+- Test suite is collectable in the default dev env again: `pytest.importorskip` guards added to `test_context_window.py`, `test_langgraph_state_tools.py`, and `test_backend_isolation.py`, which imported `langgraph`/`langchain_core`/`google.genai` unconditionally. The hybrid-search test now guards on `bm25s`, and `conftest.py` sets `KMP_DUPLICATE_LIB_OK=TRUE` so the real-FAISS and torch-backed tests (the `kb` extra) don't abort the interpreter on the duplicate OpenMP runtime.
+- **FAISS index could be left corrupt by a crash** (`knowledge_base/vector_store.py`): `save()` wrote the index in place via `faiss.write_index(self._index, path)`, so a crash mid-write left a truncated `index.faiss` — and `faiss.read_index` raises on a torn file, bricking the whole knowledge base until it was deleted by hand. The index is now written to a temp file in the same directory and `os.replace`d into position (atomic), with the temp cleaned up on failure; the misleading "mappings first is crash-safe" comment was corrected to describe what is actually guaranteed.
+- **Settings UI could persist invalid values** (`config.py::update_setting`): the non-special path used `object.__setattr__`, bypassing Pydantic entirely, so a wrong-typed or out-of-range value from the settings dialog was written straight to the instance and saved to `settings.json`, poisoning later runs. It now goes through `__pydantic_validator__.validate_assignment`, which type- and constraint-checks the value (and rejects unknown keys) before it lands — raising `ValidationError` (a `ValueError`, already handled by `apply_settings`).
+- **Ctrl+C now actually cancels an in-flight workflow** (`cli/message_processor.py`): the status bar advertised "Ctrl+C: cancel", but the binding only finished the thinking boxes — the workflow kept streaming and burning tokens. The event stream is now consumed in a cancellable task that a watcher aborts when the boxes are finished out from under it (the HITL dialog window is exempted), so Ctrl+C stops the run and prints "Cancelled."
+- **Quickstart tools were silently denied** (`README.md`): the README's `greet` example passed an unregistered raw callable and called registration "optional", but the permission engine (on by default) fails closed and denies any tool without a capability declaration on both backends. The quickstart now registers `greet` (`capabilities=EXEMPT`) and the docs state that registration is required for a tool to run.
+- **Gemini 2.5 thinking config caused HTTP 400 on every call** (`workflow/adk/manager.py`): `_get_planner` always built `ThinkingConfig(thinking_level=...)`, but `thinking_level` is a Gemini-3-only field — Gemini 2.5 models (including the default `gemini-2.5-flash`) reject it with `400 "Thinking level is not supported for this model"`. With the default `thinking_effort=medium`, every Gemini call failed (the ADK demo was unusable out of the box). The manager now uses the numeric `thinking_budget` for Gemini 2.5 models and reserves `thinking_level` for Gemini 3. Surfaced by the new live scenario tests.
+
 ## [0.5.2] - 2026-05-01
 
 ### Security

agentic_cli-0.5.3/CLAUDE.md

@@ -0,0 +1,183 @@
+# Agentic CLI - Shared Framework for Agentic Applications
+
+## Project Overview
+
+Agentic CLI is a shared library providing the core infrastructure for building domain-specific CLI applications powered by LLM agents.
+
+## Tech Stack
+
+- **Language**: Python 3.12+
+- **CLI UI**: `thinking-prompt` - enhanced CLI with thinking boxes and markdown
+- **Workflow**: Google ADK + LangGraph - dual orchestration backends (selectable via settings)
+- **Config**: `pydantic-settings` - type-safe configuration
+- **Logging**: `structlog` - structured logging
+
+## Project Structure
+
+```
+agentic-cli/
+├── src/agentic_cli/
+│   ├── __init__.py           # Package exports, lazy imports
+│   ├── config.py             # BaseSettings (pydantic-settings)
+│   ├── settings_mixins.py    # Composable settings field groups
+│   ├── settings_persistence.py # save_settings() (excludes SECRET_FIELDS)
+│   ├── constants.py          # Shared constants, truncate()
+│   ├── file_utils.py         # atomic_write_json / atomic_write_text
+│   ├── logging.py
+│   ├── cli/
+│   │   ├── app.py            # BaseCLIApp
+│   │   ├── commands.py       # Command, CommandRegistry
+│   │   ├── builtin_commands.py
+│   │   ├── workflow_controller.py  # WorkflowController (lazy/background init, orchestrator swap)
+│   │   ├── message_processor.py    # WorkflowEvent → ThinkingPromptSession rendering
+│   │   ├── settings_command.py     # /settings command
+│   │   ├── settings_introspection.py # Pydantic field → UI item introspection
+│   │   └── usage_tracker.py        # Token usage / status bar
+│   ├── workflow/
+│   │   ├── base_manager.py   # BaseWorkflowManager (abstract; service detection, tool assembly)
+│   │   ├── factory.py        # create_workflow_manager_from_settings (ADK vs LangGraph routing)
+│   │   ├── service_registry.py # get_service/require_service + ContextVar registry
+│   │   ├── events.py         # WorkflowEvent, EventType
+│   │   ├── config.py         # AgentConfig
+│   │   ├── models.py
+│   │   ├── settings.py       # Workflow/tool settings schema
+│   │   ├── retry.py          # Rate-limit retry helpers
+│   │   ├── tool_summaries.py
+│   │   ├── permissions/      # Framework-independent capability engine
+│   │   │   ├── engine.py     # PermissionEngine (deny-wins, default-ASK)
+│   │   │   ├── capabilities.py # Capability, EXEMPT
+│   │   │   ├── matchers.py   # PathMatcher, URLMatcher, ShellMatcher, StringGlobMatcher
+│   │   │   └── rules.py, store.py, prompt.py
+│   │   ├── adk/              # ADK orchestrator
+│   │   │   ├── manager.py    # GoogleADKWorkflowManager
+│   │   │   ├── event_processor.py  # ADKEventProcessor
+│   │   │   ├── permission_plugin.py # PermissionPlugin (gates tool calls)
+│   │   │   ├── task_progress_plugin.py # Emits TASK_PROGRESS events
+│   │   │   └── plugins.py    # LLM traffic logging (raw_llm_logging)
+│   │   └── langgraph/        # LangGraph orchestrator
+│   │       ├── manager.py    # LangGraphWorkflowManager
+│   │       ├── graph_builder.py # LangGraphBuilder (graph + LLM factory)
+│   │       ├── state.py
+│   │       ├── permission_wrap.py # wrap_tool_for_permission
+│   │       └── persistence/  # Checkpointers, stores
+│   ├── tools/
+│   │   ├── registry.py       # ToolRegistry, @register_tool, ToolCategory
+│   │   ├── factories.py      # Service-bound tool builders (per-manager flavors)
+│   │   ├── executor.py       # SafePythonExecutor (CORE_MODULES; SANDBOXED_MODULES gated on OS sandbox)
+│   │   ├── execution_tools.py # execute_python
+│   │   ├── knowledge_tools.py # kb_search, kb_ingest_{text,file,url}, kb_list, kb_read, kb_write_concept, kb_search_concepts
+│   │   ├── arxiv_tools.py    # search_arxiv, fetch_arxiv_paper, ingest_arxiv_paper
+│   │   ├── arxiv_source.py   # ArxivSearchSource (feed fetch, download_pdf)
+│   │   ├── pdf_utils.py      # extract_pdf_text
+│   │   ├── interaction_tools.py # ask_clarification
+│   │   ├── file_read.py      # read_file, diff_compare
+│   │   ├── file_write.py     # write_file, edit_file
+│   │   ├── glob_tool.py      # glob
+│   │   ├── grep_tool.py      # grep
+│   │   ├── search.py         # web_search (Tavily/Brave backends)
+│   │   ├── webfetch_tool.py  # web_fetch + get_or_create_fetcher (orchestrator)
+│   │   ├── memory_tools.py   # save_memory, search_memory, update_memory, delete_memory + MemoryStore
+│   │   ├── _core/           # Backend-neutral tool logic
+│   │   │   ├── planning.py  # save_plan/get_plan core (+ checkbox parsing)
+│   │   │   └── tasks.py     # save_tasks/get_tasks core (+ progress parsing)
+│   │   ├── adk/state_tools.py       # ADK-native plan/task tools (ToolContext.state)
+│   │   ├── langgraph/state_tools.py # LangGraph-native plan/task tools (Command/InjectedState)
+│   │   ├── sandbox/         # Stateful code-execution sandbox (sandbox_execute)
+│   │   ├── shell/           # 8-layer shell security (+ os_sandbox/)
+│   │   └── webfetch/        # Fetcher, converter, validator, robots, summarizer
+│   ├── knowledge_base/
+│   │   ├── models.py         # Document, SearchResult
+│   │   ├── embeddings.py     # EmbeddingService
+│   │   ├── vector_store.py   # VectorStore (FAISS)
+│   │   ├── bm25_index.py     # BM25 index (+ _bm25_backends.py: bm25s / rank_bm25)
+│   │   ├── concepts.py       # ConceptStore (concept pages)
+│   │   ├── sidecar.py        # Markdown sidecar rendering
+│   │   ├── sources.py
+│   │   ├── _mocks.py         # MockEmbeddingService, MockVectorStore (+ _mock_bm25.py)
+│   │   └── manager.py        # KnowledgeBaseManager
+│   └── persistence/
+│       └── session.py        # SessionPersistence
+├── tests/
+│   ├── conftest.py           # MockContext, shared fixtures
+│   ├── test_*.py             # Unit tests
+│   ├── tools/                # Tool-specific tests
+│   ├── workflow/             # Backend-isolation / workflow tests
+│   └── integration/          # ADK & LangGraph pipeline tests
+└── examples/                 # Demo scripts
+```
+
+## Running Commands
+
+**IMPORTANT**: Always use `conda run -n agenticcli` prefix for running commands:
+
+```bash
+# Create the environment (first time only)
+conda env create -f environment.yml
+
+# Install package
+conda run -n agenticcli pip install -e .
+
+# Run tests
+conda run -n agenticcli python -m pytest tests/ -v
+
+# Run Python
+conda run -n agenticcli python -c "from agentic_cli import BaseCLIApp; print(BaseCLIApp)"
+```
+
+## Branching Strategy
+
+- **main**: Stable branch, matches latest release. Only updated via merges from `develop` when releasing.
+- **develop**: Integration branch for ongoing work. Small fixes can be committed directly here.
+- **feature/\***: Feature branches for larger changes. Branch from `develop`, merge back to `develop`.
+- **fix/\***: Fix branches for fixing issues. Branch from `develop`, merge back to `develop`.
+- **refactor/\***: For larger refactoring changes. Branch from `develop`, merge back to `develop`.
+
+Workflow:
+1. For small fixes: commit directly to `develop`
+2. For features: create `feature/<name>` (or `fix/<name>` or `refactor/<name>`) from `develop`, work there, merge back to `develop`
+3. When ready to release: merge `develop` → `main` and tag the release
+
+### What NOT to commit
+- `docs/` is gitignored on purpose (see `.gitignore`). It is a scratchpad for review notes, plans, and internal analysis. **Never `git add docs/…` or suggest committing anything under `docs/`.** If a document belongs in the repo, it lives elsewhere (README, CHANGELOG, top-level `*.md`).
+
+## Development Principles
+
+### Code Style
+- Follow PEP 8 style guidelines
+- Use type hints throughout
+- Prefer descriptive variable names
+
+### Key Design Decisions
+- **Abstract base classes**: BaseCLIApp and BaseWorkflowManager for domain extension
+- **Dual orchestrator**: ADK and LangGraph backends, selectable via settings
+- **Lazy initialization**: Defer heavy imports until needed
+- **Event-based streaming**: Real-time updates via AsyncGenerator
+- **UI-agnostic workflow**: WorkflowEvent objects can be consumed by any UI
+
+### Key Design Patterns
+- **Tool error handling**: All tools return `{"success": bool, ...}` dicts. Never raise `ToolError`.
+- **Tool registration**: Use `@register_tool(category=..., capabilities=..., description=...)` decorator. `capabilities=` is required — pass `EXEMPT` for tools that need no permission check or a list of `Capability(name, target_arg=...)` tuples the engine matches against rules. Tools are auto-discovered via the global `ToolRegistry`.
+- **Permissions**: `workflow/permissions/` holds a framework-independent engine that evaluates declared capabilities against rules from four sources (builtin, user `~/.{app_name}/settings.json`, project `./.{app_name}/settings.json`, in-memory session). ADK + LangGraph gate tool calls via `workflow/adk/permission_plugin.py::PermissionPlugin` and `workflow/langgraph/permission_wrap.py::wrap_tool_for_permission`.
+- **Service registry**: Tools access services and shared state via `get_service(key)` from `workflow.service_registry`. A single ContextVar holds a `dict[str, Any]` set by the workflow manager during processing. Complex services (KBManager, SandboxManager, MemoryStore) are lazily created; simple state (plan string, task list) lives directly in the registry dict.
+- **Manager detection**: `BaseWorkflowManager._detect_required_managers()` scans each agent's tool names against the `_TOOL_SERVICE_MAP` (name → service key, in `base_manager.py`); `_ensure_managers_initialized()` then lazily instantiates only the services actually needed (KBManager, SandboxManager, MemoryStore, …). Adding a new service-backed tool means adding its name → service entry to `_TOOL_SERVICE_MAP`. (There is no `@requires` decorator.)
+- **Atomic writes**: Use `atomic_write_json`/`atomic_write_text` from `file_utils.py` for file persistence.
+
+### Console Output
+All console output must go through `ThinkingPromptSession` methods. Never use `rich.Console` or `print()` directly.
+
+Available session methods:
+- `session.add_response(text, markdown=True)` - Display text/markdown response
+- `session.add_rich(renderable)` - Display Rich renderables (Panel, Table, etc.)
+- `session.add_message(role, content)` - Add message to history
+- `session.add_error(content)` - Display error message
+- `session.add_warning(content)` - Display warning message
+- `session.add_success(content)` - Display success message
+- `session.clear()` - Clear the terminal screen
+
+## Testing
+
+- **Framework**: pytest with `asyncio_mode = "auto"`
+- **MockContext**: From `tests/conftest.py` — provides isolated settings and temp dirs for all tests
+- **MockVectorStore** and **MockEmbeddingService**: In `knowledge_base/_mocks.py` for testing without ML dependencies
+- **FAISS tests**: Guard with `pytest.importorskip("faiss")` since FAISS is not installed in dev env
+- **Integration tests**: `tests/integration/` covers ADK and LangGraph pipeline tests

{agentic_cli-0.5.2 → agentic_cli-0.5.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentic-cli
-Version: 0.5.2
+Version: 0.5.3
 Summary: A framework for building domain-specific agentic CLI applications
 Project-URL: Homepage, https://github.com/shoom1/agentic-cli
 Project-URL: Repository, https://github.com/shoom1/agentic-cli
@@ -43,6 +43,8 @@ Requires-Dist: langchain-core>=0.3.0; extra == 'langgraph'
 Requires-Dist: langchain-google-genai>=2.0.0; extra == 'langgraph'
 Requires-Dist: langchain-openai>=0.2.0; extra == 'langgraph'
 Requires-Dist: langchain>=0.3.0; extra == 'langgraph'
+Requires-Dist: langgraph-checkpoint-postgres>=2.0; extra == 'langgraph'
+Requires-Dist: langgraph-checkpoint-sqlite>=2.0; extra == 'langgraph'
 Requires-Dist: langgraph>=0.2.0; extra == 'langgraph'
 Description-Content-Type: text/markdown
 
@@ -141,8 +143,12 @@ import asyncio
 from agentic_cli import BaseCLIApp, BaseSettings
 from agentic_cli.cli import AppInfo
 from agentic_cli.workflow import AgentConfig
+from agentic_cli.tools import register_tool, ToolCategory
+from agentic_cli.workflow.permissions import EXEMPT
 
-# Define your tools
+# Define your tools. Tools are permission-gated, so register each one with
+# the capabilities it needs (EXEMPT = a pure function that touches nothing).
+@register_tool(category=ToolCategory.OTHER, capabilities=EXEMPT)
 def greet(name: str) -> dict:
     """Greet a person by name."""
     return {"success": True, "greeting": f"Hello, {name}!"}
@@ -390,14 +396,14 @@ def search_database(query: str, limit: int = 10) -> dict:
     return {"success": True, "results": results, "count": len(results)}
 ```
 
-Registering via `@register_tool` is optional — you can pass raw callables into `AgentConfig.tools`. Registering gives the tool metadata for the registry, capability-aware permission gating, and tool-summary formatting.
+**Registration is required for a tool to run.** The permission engine is on by default, and any tool without a capability declaration is denied at call time (fail-closed) on both the ADK and LangGraph backends. You can still pass raw callables into `AgentConfig.tools`, but unless they are registered with `@register_tool` they will be blocked — register every tool with `capabilities=` (or `EXEMPT` for pure, side-effect-free functions). Registration also gives the tool registry metadata and tool-summary formatting.
 
 ### Capabilities
 
 Tool access is gated by the **permission engine** (see the HITL section below). Each registered tool declares what it touches via `capabilities=`:
 
 - **`Capability("namespace.action", target_arg="...")`** — e.g. `Capability("filesystem.write", target_arg="path")`, `Capability("http.read", target_arg="url")`, `Capability("shell.exec", target_arg="command")`. The engine resolves `target_arg` against the actual tool-call arguments and matches against rules.
-- **`EXEMPT`** — opts the tool out of the engine entirely. Reserved for backend-internal tools (e.g. ADK `transfer_to_agent`, backend state tools).
+- **`EXEMPT`** — opts the tool out of the engine entirely. Use for tools that need no permission check: pure functions with no side effects, and backend-internal tools (e.g. ADK `transfer_to_agent`, backend state tools).
 
 ### Built-in Tools
 

{agentic_cli-0.5.2 → agentic_cli-0.5.3}/README.md

@@ -93,8 +93,12 @@ import asyncio
 from agentic_cli import BaseCLIApp, BaseSettings
 from agentic_cli.cli import AppInfo
 from agentic_cli.workflow import AgentConfig
+from agentic_cli.tools import register_tool, ToolCategory
+from agentic_cli.workflow.permissions import EXEMPT
 
-# Define your tools
+# Define your tools. Tools are permission-gated, so register each one with
+# the capabilities it needs (EXEMPT = a pure function that touches nothing).
+@register_tool(category=ToolCategory.OTHER, capabilities=EXEMPT)
 def greet(name: str) -> dict:
     """Greet a person by name."""
     return {"success": True, "greeting": f"Hello, {name}!"}
@@ -342,14 +346,14 @@ def search_database(query: str, limit: int = 10) -> dict:
     return {"success": True, "results": results, "count": len(results)}
 ```
 
-Registering via `@register_tool` is optional — you can pass raw callables into `AgentConfig.tools`. Registering gives the tool metadata for the registry, capability-aware permission gating, and tool-summary formatting.
+**Registration is required for a tool to run.** The permission engine is on by default, and any tool without a capability declaration is denied at call time (fail-closed) on both the ADK and LangGraph backends. You can still pass raw callables into `AgentConfig.tools`, but unless they are registered with `@register_tool` they will be blocked — register every tool with `capabilities=` (or `EXEMPT` for pure, side-effect-free functions). Registration also gives the tool registry metadata and tool-summary formatting.
 
 ### Capabilities
 
 Tool access is gated by the **permission engine** (see the HITL section below). Each registered tool declares what it touches via `capabilities=`:
 
 - **`Capability("namespace.action", target_arg="...")`** — e.g. `Capability("filesystem.write", target_arg="path")`, `Capability("http.read", target_arg="url")`, `Capability("shell.exec", target_arg="command")`. The engine resolves `target_arg` against the actual tool-call arguments and matches against rules.
-- **`EXEMPT`** — opts the tool out of the engine entirely. Reserved for backend-internal tools (e.g. ADK `transfer_to_agent`, backend state tools).
+- **`EXEMPT`** — opts the tool out of the engine entirely. Use for tools that need no permission check: pure functions with no side effects, and backend-internal tools (e.g. ADK `transfer_to_agent`, backend state tools).
 
 ### Built-in Tools
 

{agentic_cli-0.5.2 → agentic_cli-0.5.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "agentic-cli"
-version = "0.5.2"
+version = "0.5.3"
 description = "A framework for building domain-specific agentic CLI applications"
 readme = "README.md"
 license = "MIT"
@@ -56,6 +56,10 @@ langgraph = [
     "langchain-openai>=0.2.0",
     "langchain-anthropic>=0.2.0",
     "langchain-google-genai>=2.0.0",
+    # Persistent checkpointer backends (sqlite/postgres store_type). The async
+    # savers are required because the manager streams via astream_events.
+    "langgraph-checkpoint-sqlite>=2.0",
+    "langgraph-checkpoint-postgres>=2.0",
 ]
 
 [project.scripts]

{agentic_cli-0.5.2 → agentic_cli-0.5.3}/src/agentic_cli/__init__.py

@@ -92,4 +92,4 @@ __all__ = [
     "CLISettingsMixin",
 ]
 
-__version__ = "0.5.2"
+__version__ = "0.5.3"

{agentic_cli-0.5.2 → agentic_cli-0.5.3}/src/agentic_cli/cli/app.py

@@ -456,6 +456,29 @@ class BaseCLIApp:
         else:
             logger.error("session_save_on_exit_failed", error=result.get("error"))
 
+    async def _extract_session_facts_on_exit(self) -> None:
+        """Extract key facts from the session into memory on exit (if enabled).
+
+        Gated by the ``auto_extract_session_facts`` setting; a no-op when the
+        workflow isn't ready or has no memory store. Never raises — fact
+        extraction must not block a clean shutdown.
+        """
+        if not getattr(self._settings, "auto_extract_session_facts", False):
+            return
+
+        if not self._workflow_controller.is_ready:
+            return
+
+        workflow = self._workflow_controller.workflow
+        try:
+            facts = await workflow.on_session_end()
+        except Exception:
+            logger.debug("session_fact_extraction_on_exit_failed", exc_info=True)
+            return
+
+        if facts:
+            logger.info("session_facts_extracted", count=len(facts))
+
     async def run(self) -> None:
         """Run the main application loop."""
         logger.info("repl_starting")
@@ -474,6 +497,9 @@ class BaseCLIApp:
             # Run the session - user sees prompt immediately!
             await self.session.run_async()
 
+        # Extract session facts into memory on exit (if enabled)
+        await self._extract_session_facts_on_exit()
+
         # Save persistent session on exit
         if self._session_id:
             await self._save_session_on_exit()

{agentic_cli-0.5.2 → agentic_cli-0.5.3}/src/agentic_cli/cli/message_processor.py

@@ -7,6 +7,7 @@ This module provides:
 from __future__ import annotations
 
 import asyncio
+from contextlib import suppress
 from dataclasses import dataclass, field
 from typing import TYPE_CHECKING, ClassVar
 
@@ -74,6 +75,10 @@ class _EventProcessingState:
     workflow_controller: "WorkflowController | None" = field(default=None, repr=False)
     status_line: str = "Processing..."
     thinking_started: bool = False
+    # True while a HITL dialog is on screen: during that window there are no
+    # active thinking boxes, so the Ctrl+C watcher must not mistake the absence
+    # of boxes for a cancel request.
+    in_hitl: bool = False
     thinking_content: list[str] = field(default_factory=list)
     response_content: list[str] = field(default_factory=list)
     # Prevents double-counting when LangGraph emits both CONTEXT_TRIMMED and LLM_USAGE
@@ -189,16 +194,21 @@ class MessageProcessor:
         # deadlocking the workflow runner.
         async def _handle_input(request: "UserInputRequest") -> str:
             nonlocal events_ctx
-            if state.thinking_started and events_ctx is not None:
-                events_ctx.finish(add_to_history=False)
-                state.thinking_started = False
-
-            response = await self._prompt_user_input(request, ui)
-
-            events_ctx = ui.start_thinking(
-                state.get_status, content_format="ansi"
-            )
-            state.thinking_started = True
+            # Mark the HITL window before tearing down the events box so the
+            # cancel watcher doesn't read "no active boxes" as a Ctrl+C.
+            state.in_hitl = True
+            try:
+                if state.thinking_started and events_ctx is not None:
+                    events_ctx.finish(add_to_history=False)
+                    state.thinking_started = False
+
+                response = await self._prompt_user_input(request, ui)
+            finally:
+                events_ctx = ui.start_thinking(
+                    state.get_status, content_format="ansi"
+                )
+                state.thinking_started = True
+                state.in_hitl = False
             return response
 
         workflow.set_input_callback(_handle_input)
@@ -210,13 +220,33 @@ class MessageProcessor:
                     )
                     state.thinking_started = True
 
-                    async for event in workflow.process(
-                        message=message,
-                        user_id=settings.default_user,
-                    ):
-                        handler = dispatch.get(event.type)
-                        if handler is not None:
-                            await handler(self, event, state, ui, settings, workflow)
+                    # Consume the event stream in a cancellable task so Ctrl+C
+                    # can abort an in-flight run. thinking_prompt's Ctrl+C
+                    # binding finishes all thinking boxes (so ui.is_thinking
+                    # flips False) but never cancels our coroutine, so we watch
+                    # for that and cancel the task ourselves.
+                    async def _consume() -> None:
+                        async for event in workflow.process(
+                            message=message,
+                            user_id=settings.default_user,
+                        ):
+                            handler = dispatch.get(event.type)
+                            if handler is not None:
+                                await handler(
+                                    self, event, state, ui, settings, workflow
+                                )
+
+                    proc_task = asyncio.create_task(_consume())
+                    if await self._watch_for_cancel(proc_task, ui, state):
+                        # Ctrl+C already finished every active box; just drop
+                        # our now-dead references so the next turn starts clean.
+                        state.thinking_started = False
+                        self._task_box = None
+                        self._last_task_content = None
+                        ui.add_warning("Cancelled.")
+                        workflow_controller.update_status_bar(ui)
+                        logger.info("message_cancelled_by_user")
+                        break
 
                     # Finish events box only (don't add status to history)
                     if state.thinking_started and events_ctx is not None:
@@ -262,6 +292,42 @@ class MessageProcessor:
                 self._last_task_content if self._task_box else None
             )
 
+    async def _watch_for_cancel(
+        self,
+        proc_task: "asyncio.Task[None]",
+        ui: "ThinkingPromptSession",
+        state: _EventProcessingState,
+    ) -> bool:
+        """Watch a running workflow task and cancel it on Ctrl+C.
+
+        thinking_prompt's Ctrl+C binding finishes all active thinking boxes
+        (so ``ui.is_thinking`` becomes False) but does not cancel the coroutine
+        driving the workflow. We poll for that transition — ignoring the HITL
+        window, when boxes are legitimately absent — and cancel the task when
+        it happens.
+
+        Args:
+            proc_task: Task consuming the workflow event stream.
+            ui: UI session (provides the public ``is_thinking`` box state).
+            state: Shared processing state (``in_hitl`` guards the dialog window).
+
+        Returns:
+            True if the task was cancelled by the user. Otherwise False, after
+            re-raising any exception the task raised.
+        """
+        while True:
+            done, _ = await asyncio.wait({proc_task}, timeout=0.1)
+            if proc_task in done:
+                break
+            if not state.in_hitl and not ui.is_thinking:
+                proc_task.cancel()
+                with suppress(asyncio.CancelledError):
+                    await proc_task
+                return True
+        # Task completed on its own — surface its result/exception.
+        proc_task.result()
+        return False
+
     async def _prompt_user_input(
         self,
         request: "UserInputRequest",

{agentic_cli-0.5.2 → agentic_cli-0.5.3}/src/agentic_cli/config.py

@@ -119,7 +119,12 @@ class BaseSettings(WorkflowSettingsMixin, AppSettingsMixin, CLISettingsMixin, Py
         elif key == "thinking_effort":
             self.set_thinking_effort(value)
         else:
-            object.__setattr__(self, key, value)
+            # Validate through Pydantic instead of object.__setattr__ so the
+            # value is type-checked and constraint-checked before it lands on
+            # the instance (and is later persisted to settings.json). An
+            # invalid value or unknown key raises ValidationError, which is a
+            # subclass of ValueError — exactly what callers already handle.
+            self.__pydantic_validator__.validate_assignment(self, key, value)
 
     @classmethod
     def settings_customise_sources(

{agentic_cli-0.5.2 → agentic_cli-0.5.3}/src/agentic_cli/file_utils.py

@@ -2,6 +2,8 @@
 
 import fcntl
 import json
+import os
+import tempfile
 import time
 from contextlib import contextmanager
 from pathlib import Path
@@ -58,11 +60,31 @@ def sanitize_filename(name: str) -> str:
 
 
 def _atomic_write(path: Path, content: str) -> None:
-    """Write content to a file atomically (write tmp, then rename)."""
+    """Write content to a file atomically and durably.
+
+    Writes to a uniquely-named temp file in the same directory, flushes and
+    fsyncs it, then atomically renames it over the target. Notes:
+    - Unique temp name (tempfile.mkstemp) so two concurrent writers can't
+      truncate each other's temp file the way a fixed ``.tmp`` name allows.
+    - fsync before the rename so a crash can't persist the rename ahead of the
+      data and leave a torn/empty file in place of the previously-good one.
+    - Explicit UTF-8 so output doesn't depend on the locale (a C/POSIX locale
+      would otherwise raise UnicodeEncodeError on non-ASCII content).
+    """
     path.parent.mkdir(parents=True, exist_ok=True)
-    tmp_path = path.with_suffix(path.suffix + ".tmp")
-    tmp_path.write_text(content)
-    tmp_path.replace(path)
+    fd, tmp_name = tempfile.mkstemp(
+        dir=str(path.parent), prefix=f".{path.name}.", suffix=".tmp"
+    )
+    tmp_path = Path(tmp_name)
+    try:
+        with os.fdopen(fd, "w", encoding="utf-8") as f:
+            f.write(content)
+            f.flush()
+            os.fsync(f.fileno())
+        os.replace(tmp_path, path)
+    except BaseException:
+        tmp_path.unlink(missing_ok=True)
+        raise
 
 
 def atomic_write_json(path: Path, data: Any, indent: int = 2) -> None:

{agentic_cli-0.5.2 → agentic_cli-0.5.3}/src/agentic_cli/knowledge_base/vector_store.py

@@ -6,6 +6,8 @@ Provides FAISS-based vector storage and similarity search.
 from __future__ import annotations
 
 import json
+import os
+import tempfile
 import threading
 from pathlib import Path
 from typing import TYPE_CHECKING
@@ -207,7 +209,16 @@ class VectorStore:
         self._next_id = len(new_id_map)
 
     def save(self) -> None:
-        """Persist index and mappings to disk."""
+        """Persist index and mappings to disk.
+
+        Both files are written atomically (temp file + ``os.replace``) so a
+        crash mid-write can never leave a truncated ``index.faiss`` — a torn
+        index is fatal because ``faiss.read_index`` raises on load, which would
+        brick the whole knowledge base. The index is committed before the
+        mappings: each file is always complete on its own, and a crash in the
+        brief window between the two replaces leaves a complete (if slightly
+        stale) pair rather than a corrupt index.
+        """
         with self._lock:
             if self._index is None:
                 return
@@ -217,9 +228,24 @@ class VectorStore:
             # Ensure directory exists
             self.index_path.parent.mkdir(parents=True, exist_ok=True)
 
-            # Save mappings first (atomic) — if we crash after this but
-            # before the index write, the mappings are still valid and
-            # the old index can be loaded safely.
+            # Write the FAISS index atomically: faiss.write_index() takes a
+            # path and writes in place (non-atomic), so write to a temp file in
+            # the same directory and os.replace() it into position.
+            fd, tmp_name = tempfile.mkstemp(
+                dir=str(self.index_path.parent),
+                prefix=f".{self.index_path.name}.",
+                suffix=".tmp",
+            )
+            os.close(fd)  # faiss writes by path, not file descriptor
+            tmp_path = Path(tmp_name)
+            try:
+                faiss.write_index(self._index, str(tmp_path))
+                os.replace(tmp_path, self.index_path)
+            except BaseException:
+                tmp_path.unlink(missing_ok=True)
+                raise
+
+            # Mappings written after the index (also atomically).
             mappings_path = self.index_path.with_suffix(".mappings.json")
             mappings = {
                 "id_map": {str(k): v for k, v in self._id_map.items()},
@@ -228,9 +254,6 @@ class VectorStore:
             }
             atomic_write_json(mappings_path, mappings)
 
-            # Save FAISS index
-            faiss.write_index(self._index, str(self.index_path))
-
     def load(self) -> None:
         """Load index and mappings from disk."""
         if not self.index_path.exists():