agentic-cli 0.6.0__tar.gz → 0.6.1__tar.gz

{agentic_cli-0.6.0 → agentic_cli-0.6.1}/.github/workflows/ci.yml

@@ -68,6 +68,38 @@ jobs:
           conda run -n agenticcli python -m pytest
           tests/examples/test_research_demo_wheel.py -m wheel -v
 
+  latex-engine:
+    name: LaTeX engine tests
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        shell: bash -el {0}
+    steps:
+      - uses: actions/checkout@v4
+
+      # compile_document's lockdown (no shell escape, paranoid file access) is
+      # enforced by TeX itself, so it can only be verified against a real engine.
+      - name: Install TeX Live (pdflatex + latexmk)
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y --no-install-recommends \
+            texlive-latex-base texlive-latex-recommended latexmk
+
+      - name: Set up conda env (agenticcli)
+        uses: conda-incubator/setup-miniconda@v3
+        with:
+          miniforge-version: latest
+          environment-file: environment.yml
+          activate-environment: agenticcli
+
+      # Targets the file: a bare `-m latex` still collects the whole suite.
+      - name: Run LaTeX engine tests (fail if the engine is missing)
+        env:
+          LATEX_REQUIRE: "1"
+        run: >
+          conda run -n agenticcli python -m pytest
+          tests/tools/test_document_compile_latex.py -m latex -v
+
   docker-isolation:
     name: Docker isolation tests
     runs-on: ubuntu-latest

{agentic_cli-0.6.0 → agentic_cli-0.6.1}/CHANGELOG.md

@@ -7,6 +7,45 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.6.1] - 2026-09-27
+
+Security and stability fixes for 0.6.0. The permission engine now judges the
+location a tool actually acts on, approving a search tool no longer approves
+every URL, the OS sandbox protects credentials, the app's config and `.git`,
+and `compile_document` can no longer read files outside the project or run
+other programs. Tool errors, unanswerable permission prompts and HTTP error
+pages no longer end a turn or pose as content, and the Python timeouts take
+effect. Two interface changes, see *Changed*: `web_search` declares
+`search.web`, and `compile_document` requires `output_pdf`.
+
+### Security
+- **The permission engine now judges the location a tool actually acts on.** `${workdir}`, `${home}` and `${app_name}` were expanded in tool arguments as well as in rules, so a crafted path could be judged inside the project while the tool acted outside it; and the engine expanded `~` and anchored relative paths to the project while the file tools did neither. Both sides now resolve arguments with one function, `agentic_cli.paths.resolve_path`: placeholders expand only in rule patterns, `~` expands in the tools too, relative paths resolve against the process's current directory, saved grants load literally, an argument of `*` is a literal name rather than the wildcard (so approving it can no longer grant every read), and an argument that cannot name a path is denied. `compile_document` also refuses an `output_pdf` that is a symlink and fixes its destination before compiling.
+- **Approving a search tool no longer approves every URL.** `web_search` and the arXiv tools declared `http.read` with no target, so an approval was saved as `http.read *` and silently covered `web_fetch` and `kb_ingest_url` for any URL. The arXiv tools now declare their fixed arXiv endpoints with the new `Capability(..., target=...)`, and the PDF download refuses anything outside `https://arxiv.org/pdf/`. Filesystem, network and shell capabilities with no target warn at registration (an error in 0.7.0) and are approved one call at a time, and `http.read *`-style grants saved by 0.6.0 are dropped on load. A filesystem grant now covers the directory it names instead of that directory's parent, and never the filesystem root or a directory above home.
+- **LangGraph no longer grants a tool's permissions by name.** Its permission wrapper looked tools up by name, so on the LangGraph backend a plain function sharing a registered tool's name inherited that tool's capabilities, or ran unchecked if the tool was `EXEMPT`. It now resolves tools by registry identity, as the ADK backend has since 0.6.0.
+- **The OS sandbox around `execute_python` protects credentials, the app's config and `.git`.** Sandboxed code could read `~/.ssh`, `~/.aws` and other credential stores, the app's own `~/.{app_name}` (settings, permission grants, `.env`) and the project's `.env`; only `.git/hooks` and `.git/config` were write-protected, so the whole `.git` could be moved aside and replaced; and when the app was started from the home directory, all of home was writable. These locations are now denied whatever the configured policy says, the whole `.git` is write-protected, and a working directory that is home, an ancestor of home, or `/` is no longer made writable.
+- **Sandbox sessions can no longer reach each other.** `sandbox_execute` session IDs were sanitized into directory and container names, so an empty ID named the directory holding every session (which the Docker backend mounts into the container) and IDs such as `a.b` and `a_b` shared one. IDs must now be 1–64 letters, digits, `-` or `_`, and anything else is refused. Docker container names also carry a per-process suffix, so two app processes using the same session ID no longer collide.
+- **`compile_document` can no longer read files outside the project or run other programs.** TeX reads any file the user can read by default, so a document could `\input` an absolute path, a `..` path or a project dotfile such as `.env` (or dump any file with `\pdffiledump`), and the contents came back to the model in the log or the PDF — past the `filesystem.read` rules. And while `pdflatex` ran with `-no-shell-escape`, the `pdflatex` runs `latexmk` makes got TeX Live's restricted shell escape, which runs a list of programs. The TeX process now runs with shell escape off and paranoid file access (`shell_escape=f`, `openin_any=p`, `openout_any=p`), and the host's `TEXMFOUTPUT` is no longer passed through. Documents still find files by relative name in their own directory, `assets_dir` and the TeX installation. A new CI job verifies this against a real TeX Live.
+- **`/settings` saves only what you changed, and never a credential.** It saved the whole live settings object, so a value that came from the environment for one run (`os_sandbox_enabled=false`, `raw_llm_logging=true`) or was derived at startup was written to the config and kept applying, and an application's own API-key fields were written in plaintext. It now saves exactly the fields the dialog changed (`save_settings(keys=...)`), nothing when nothing changed, and no field named like a credential or typed `SecretStr` is ever written.
+
+### Changed
+- **`web_search` declares its own capability, `search.web`.** Sending queries to the configured search provider is a different decision from fetching arbitrary URLs. Rules written for `http.read` no longer apply to `web_search`; add a `search.web` rule if you had one.
+- **`compile_document` requires `output_pdf`.** Without it, the PDF was written next to the source with no `filesystem.write` check, so it could overwrite an existing PDF there that nothing had approved. The destination is now always given and always checked; an empty value is refused. The report-writer skill and the research demo already pass it.
+
+### Deprecated
+- **`agentic_cli.tools.google_search_tool` — deprecated, removed in 0.7.0.** It re-exported ADK's built-in `google_search`, which runs inside the model, so the permission engine never checks it. Use `agentic_cli.tools.web_search`. This reverses the 0.1.2 advice to use ADK's tool; the web search client removed then returned in 0.3.2. For native Google Search, import `GoogleSearchTool` from `google.adk.tools.google_search_tool`; in this framework it works only as an agent's sole tool, with `include_state_tools=False`. The name is no longer in `agentic_cli.tools.__all__`, importing the package loads no ADK code, every use warns, and a reference in agent configuration warns with a visible `FutureWarning`.
+
+### Fixed
+- **A tool result containing `[/…]` no longer fails the turn in the CLI.** Tool names and output were inserted into Rich markup unescaped, so an error such as `File not found: notes[/draft].md` raised a markup error after the tool had already run, and text like `[bold red]` restyled the output. They are now escaped and shown literally.
+- **`update_memory` no longer breaks every Gemini request.** Its `tags` default was an internal `object()` marker, which ADK copied into the tool declaration, so any ADK agent on Gemini that included the tool failed before reaching the model. `tags` now defaults to `None`, which leaves tags unchanged, and an empty list clears them: models often send `null` for an argument they mean to omit, so `null` no longer wipes tags. A test now serializes every framework tool's declaration.
+- **A permission prompt nobody can answer now denies the call instead of ending the turn.** With no input callback installed (a headless run, or a script driving the manager directly), a tool call with no matching rule raised out of the permission check and aborted the turn. The engine now denies the call with a reason the model can read, and a prompt that fails for any other reason is also a denial; cancelling the turn still cancels it. `ask_clarification` returns an error result in the same situation. `request_user_input` now raises `UserInputUnavailable`, a `RuntimeError` subclass exported from `agentic_cli.workflow`.
+- **A tool that raises no longer ends the turn on the ADK backend.** ADK re-raises a tool's exception unless a plugin answers for it, so one bad call aborted the whole turn. The new `ToolErrorPlugin` turns the exception into `{"success": False, "error": ...}` so the model can recover; a call to a tool that does not exist gets the same treatment. LangGraph already did this. The framework tools that raised on ordinary bad input now return an error themselves: `write_file` when a parent path is a file, `edit_file` with an invalid regex replacement such as `\d`, `diff_compare` on a binary or unreadable file, and `job_list` with an unknown state.
+- **`web_fetch` no longer treats an error page as the page.** A 404 or 500 response was returned as fetched content: `web_fetch` summarized it, `kb_ingest_url` stored it in the knowledge base, an arXiv PDF download accepted it, and it stayed cached for the cache lifetime. A 4xx or 5xx response is now a failure that names the status and is not cached. A `charset` the server declares that Python cannot decode with no longer raises: the body is decoded as UTF-8, and robots.txt rules still apply in that case instead of being ignored.
+- **A `/settings` change that fails is undone instead of saved.** The dialog applied fields one at a time: when a later value was invalid, or the workflow could not restart with the new model or orchestrator, it reported the error but kept the earlier changes, and `/settings` saved them, so a model the app could not start with was applied again on the next run. After a failed model switch the session also stayed down on that model. `apply_settings` is now all or nothing: on failure every field is restored, the workflow is restarted on the model it was running, nothing is saved, and it returns `False` (`True` on success).
+- **`python_executor_timeout` and `sandbox_timeout` now take effect.** `execute_python` and `sandbox_execute` had their own defaults in the tool signature (30 s and 120 s) and always passed them on, so the configured timeouts were never used. A call that gives no timeout now uses the setting, a timeout the call does give is used as given, and zero or a negative value is refused.
+- **A timed-out `sandbox_execute` cell on the local backend is stopped, and the session keeps working.** The local Jupyter backend applied its timeout to the gap between two outputs, so a cell that printed steadily never timed out; and when a timeout did fire, the cell kept running, so every later call in that session queued behind it and timed out as well. The timeout now bounds the whole cell. When it expires, the cell is interrupted and the session's variables are kept; a cell that ignores the interrupt gets a new kernel, and the result says the session's variables were lost. The Docker backend already worked this way.
+- **`write_file` and `edit_file` no longer change a file's permissions.** Atomic writes go through a temp file that is always created 0600 and then replaces the original, so editing a `0755` script made it non-executable and unreadable to anyone else, and every new file was 0600. An existing file now keeps its permission bits and a new file gets the process default (0666 minus the umask), as a plain write would; setuid/setgid are not carried over. The framework's own state files (settings, grants, memory, knowledge base) stay private.
+- **`compile_document` allows 5 minutes by default instead of 2.** The timeout covers the whole build (several `pdflatex` passes plus `bibtex`/`biber`), which a long or figure-heavy document can take more than two minutes to finish. An explicit `timeout_s` is still used as given.
+
 ## [0.6.0] - 2026-08-04
 
 Long-running jobs, durable sessions, a Docker sandbox backend, five P0 security

{agentic_cli-0.6.0 → agentic_cli-0.6.1}/CLAUDE.md

@@ -23,6 +23,7 @@ agentic-cli/
 │   ├── settings_persistence.py # Trust-split save (PROJECT_SETTABLE_KEYS → project, rest → user config; excludes SECRET_FIELDS)
 │   ├── constants.py          # Shared constants, truncate()
 │   ├── file_utils.py         # atomic_write_json / atomic_write_text
+│   ├── paths.py              # resolve_path: the one interpretation of a path argument
 │   ├── logging.py
 │   ├── cli/
 │   │   ├── app.py            # BaseCLIApp
@@ -53,6 +54,7 @@ agentic-cli/
 │   │   │   ├── event_processor.py  # ADKEventProcessor
 │   │   │   ├── permission_plugin.py # PermissionPlugin (gates tool calls)
 │   │   │   ├── task_progress_plugin.py # Emits TASK_PROGRESS events
+│   │   │   ├── tool_error_plugin.py # Tool exception → error result (turn survives)
 │   │   │   └── plugins.py    # LLM traffic logging (raw_llm_logging)
 │   │   └── langgraph/        # LangGraph orchestrator
 │   │       ├── manager.py    # LangGraphWorkflowManager
@@ -155,10 +157,11 @@ Workflow:
 - **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 error handling**: All tools return `{"success": bool, ...}` dicts. Never raise `ToolError`. An exception that still escapes a tool is a bug, but it costs one call rather than the turn: on ADK, `workflow/adk/tool_error_plugin.py::ToolErrorPlugin` turns it (and a call to a tool name that does not exist) into an error dict; LangGraph's `ToolNode` runs with `handle_tool_errors=True`.
 - **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`.
 - **ADK transfer-tool description**: ADK builds `transfer_to_agent`'s model-visible description from its docstring, which through 1.37.0 tells the model to "use TransferToAgentTool instead of this function directly" — advice meant for Python callers that made Gemini emit the class name, which ADK then rejects. `workflow/adk/transfer_tool_description.py` is a `before_model_callback` plugin that rewrites that description on the prepared `LlmRequest`: only when the tool is the **exact** native `TransferToAgentTool` (an application tool sharing the name is untouched) and only while the misleading text is present, so it is idempotent and becomes a **no-op** once the installed ADK ships a corrected docstring (upstream fixed it in 2.x). Only `description` is written — declaration name, parameter schema, required fields and the agent-name enum are preserved, and the upstream function's `__doc__` is never mutated.
 - **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). Interactive "Allow always" grants persist to `~/.{app_name}/project_grants.json` keyed by resolved project path — user-owned, never into the project settings file a repo could ship. ADK + LangGraph gate tool calls via `workflow/adk/permission_plugin.py::PermissionPlugin` and `workflow/langgraph/permission_wrap.py::wrap_tool_for_permission`.
+- **Permission targets vs. patterns**: a tool argument is a *target*, a rule's target is a *pattern*. Matchers canonicalize them with different methods: `canonicalize_pattern` expands `${workdir}`/`${home}`/`${app_name}` and anchors relative filesystem patterns to the project; `canonicalize_target` expands nothing and resolves a path exactly as the tool will. Any tool that takes a path argument must resolve it with `agentic_cli.paths.resolve_path` (the same function `PathMatcher.canonicalize_target` uses), so the engine judges the location the tool acts on. `tests/tools/test_path_contract.py` fails when a new filesystem tool has no contract case. Filesystem, `http.*` and shell capabilities must name their resource (`target_arg=` or a fixed `target=`): a targetless one resolves to the wildcard, so it warns at registration and is never remembered as a grant, and saved `http.read *`-style grants are dropped on load. Filesystem grants cover the named directory (a file's own directory), never `/` or anything above home.
 - **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**: tools declare their own service needs — `@register_tool(..., requires="kb_manager")` (or a tuple for several) — and the key is validated against `service_registry.KNOWN_SERVICE_KEYS` at registration (only *constructible* services are declarable; `user_kb_manager` is created together with `kb_manager`). `BaseWorkflowManager._detect_required_managers()` reads that metadata off the registry for each agent's tools (by registry identity, so `register(func, name=...)`'s original callable still declares its services); `_build_services()` then lazily constructs only the services actually needed, into a local dict that is released in full if a later constructor raises (nothing is published, so nothing else could close it). A downstream tool may request any framework-provided service without editing the framework; there is no mechanism for registering new service *types*, and no central name→service map.
 - **Canonical tool names + permission identity**: `ToolDefinition.name` is the single identity. `register_tool(name="public_name")` wraps the callable so `func.__name__` is the registered name (backends derive the model-visible name from the callable). Permission gating **and tool assembly** resolve through a **registry-owned identity binding**: each `ToolRegistry` owns a `id(obj) → (weakref, definition)` map (`registry.bind_identity()`/`identify()`; the module-level `tools.registry.bind_tool_identity()`/`identify_tool()` answer for `get_registry()`). Every hit is confirmed with `is` against the weak reference, so neither a name, a class name, nor a forged `__eq__`/`__hash__` can stand in for it, and a recycled address inherits nothing. Identity is **per registry** — a tool registered into an application's own `ToolRegistry` is not one of the framework's, so it stays untouched during assembly and is denied at permission time — which is also what lets a short-lived registry, its definitions and their closures be garbage collected. Everything the framework issues is bound at its construction site: registered callables, factory service-bound variants, renamed wrappers, and the native ADK tool objects the framework builds (skill tools, in `tools/skills/toolset.py`). `workflow/adk/permission_plugin.py` unwraps `.func` only for the exact ADK types whose contract is to call it (`FunctionTool`, `LongRunningFunctionTool`, and ADK's own `TransferToAgentTool`), and gates genuine `McpTool` instances (`isinstance`, since ADK creates them on connect) under a synthetic `mcp` capability. `TransferToAgentTool` is a `FunctionTool` **subclass** ADK auto-injects into any agent with `sub_agents`; matching only exact `FunctionTool` denied the built-in routing tool as unregistered, so delegation could not work at all. It is trusted on exactly the same terms as the others — ADK constructs it as `super().__init__(func=transfer_to_agent)` and overrides only `_get_declaration()` (to add the agent-name enum), never `run_async`, so what it invokes is still exactly `self.func`. Listing the **exact class** keeps every other subclass, forged object and same-named tool denied; no name authority is restored. Anything unbound is denied — and, in assembly (service detection, service-tool substitution, canonicalization, long-running wrapping), left exactly as the application supplied it: a plain callable named `kb_search` is not the framework's tool and must not be given its services, its service-bound variant, or its long-running contract. Substitution additionally requires the service variant to *be* that same definition (`identify_tool(variant) is definition`); factories bind each closure to the exact module-level tool it re-binds, so a tool an application has taken over keeps its own implementation.
@@ -169,7 +172,7 @@ Workflow:
 - **Session identity**: durable sessions are addressed by `SessionRef(app_name, user_id, session_id)` (`workflow/sessions.py`). Every session hook (`session_exists`/`list_sessions`/`delete_session`/`recent_messages`/`load_session`) takes an optional `user_id`, defaulting to `settings.default_user` only when the caller omits it. Backends without a session store leave `supports_sessions` False, and the base hooks raise `NotImplementedError` rather than answering with a misleading `False`/`[]`.
 - **Active turn**: the in-flight `(user, session)` is a `ContextVar` (`workflow/sessions.py::get_active_turn`), set with a token by `_workflow_context()` — concurrent turns on one manager stay isolated and nesting restores the outer turn.
 - **Resource ownership**: `cleanup()` is idempotent and awaits an async `close()` on owned resources (`BaseWorkflowManager._aclose_owned`); `WorkflowController.close()` is the single shutdown path (cancel init → shut executor → clean manager).
-- **Atomic writes**: Use `atomic_write_json`/`atomic_write_text` from `file_utils.py` for file persistence.
+- **Atomic writes**: Use `atomic_write_json`/`atomic_write_text` from `file_utils.py` for file persistence. They create files private (0600), right for the framework's own state; a write to a file the user owns (`write_file`, `edit_file`) passes `preserve_mode=True`, which keeps an existing file's permission bits and gives a new file the process default.
 
 ### Console Output
 All console output must go through `ThinkingPromptSession` methods. Never use `rich.Console` or `print()` directly.

{agentic_cli-0.6.0 → agentic_cli-0.6.1}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: agentic-cli
-Version: 0.6.0
+Version: 0.6.1
 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
@@ -463,7 +463,7 @@ from agentic_cli.workflow.permissions import Capability, EXEMPT
 
 @register_tool(
     category=ToolCategory.NETWORK,
-    capabilities=[Capability("http.read")],
+    capabilities=[Capability("http.read", target="https://db.example.com/search")],
     description="Search the database for matching records.",
 )
 def search_database(query: str, limit: int = 10) -> dict:
@@ -526,6 +526,8 @@ rather than silently picking one by import order.
 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.
+- **`Capability("namespace.action", target="...")`** — a fixed target, for a tool that always reaches the same resource, e.g. `Capability("http.read", target="https://export.arxiv.org/api/query")`.
+- Filesystem, network (`http.*`) and shell capabilities must name their resource with `target_arg` or `target`. Without one the target is the wildcard: the tool warns at registration, and every approval of it applies to that one call only, because remembering it would approve the capability for every resource.
 - **`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
@@ -719,7 +721,7 @@ from agentic_cli.tools import memory_tools
 
 #### HITL (Human-in-the-Loop)
 
-Tool calls are gated by the **permission engine** (`workflow/permissions/`). Each tool declares a list of capabilities (e.g. `filesystem.write(path=...)`); the engine evaluates them against rules from four sources (builtin defaults, user `~/.{app_name}/settings.json`, project `./.{app_name}/settings.json`, in-memory session). When no rule matches, the user is prompted with `Allow once` / `Allow for this session` / `Allow always for this project` / `Deny`.
+Tool calls are gated by the **permission engine** (`workflow/permissions/`). Each tool declares a list of capabilities (e.g. `filesystem.write(path=...)`); the engine evaluates them against rules from four sources (builtin defaults, user `~/.{app_name}/settings.json`, project `./.{app_name}/settings.json`, in-memory session). When no rule matches, the user is prompted with `Allow once` / `Allow for this session` / `Allow always for this project` / `Deny`. A filesystem grant covers the directory it names (or the directory a file is in), never the filesystem root or a directory above your home.
 
 **"Allow always" grants are user-owned, not project-owned.** They persist to
 `~/.{app_name}/project_grants.json`, keyed by the *resolved project path*, so

{agentic_cli-0.6.0 → agentic_cli-0.6.1}/README.md

@@ -406,7 +406,7 @@ from agentic_cli.workflow.permissions import Capability, EXEMPT
 
 @register_tool(
     category=ToolCategory.NETWORK,
-    capabilities=[Capability("http.read")],
+    capabilities=[Capability("http.read", target="https://db.example.com/search")],
     description="Search the database for matching records.",
 )
 def search_database(query: str, limit: int = 10) -> dict:
@@ -469,6 +469,8 @@ rather than silently picking one by import order.
 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.
+- **`Capability("namespace.action", target="...")`** — a fixed target, for a tool that always reaches the same resource, e.g. `Capability("http.read", target="https://export.arxiv.org/api/query")`.
+- Filesystem, network (`http.*`) and shell capabilities must name their resource with `target_arg` or `target`. Without one the target is the wildcard: the tool warns at registration, and every approval of it applies to that one call only, because remembering it would approve the capability for every resource.
 - **`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
@@ -662,7 +664,7 @@ from agentic_cli.tools import memory_tools
 
 #### HITL (Human-in-the-Loop)
 
-Tool calls are gated by the **permission engine** (`workflow/permissions/`). Each tool declares a list of capabilities (e.g. `filesystem.write(path=...)`); the engine evaluates them against rules from four sources (builtin defaults, user `~/.{app_name}/settings.json`, project `./.{app_name}/settings.json`, in-memory session). When no rule matches, the user is prompted with `Allow once` / `Allow for this session` / `Allow always for this project` / `Deny`.
+Tool calls are gated by the **permission engine** (`workflow/permissions/`). Each tool declares a list of capabilities (e.g. `filesystem.write(path=...)`); the engine evaluates them against rules from four sources (builtin defaults, user `~/.{app_name}/settings.json`, project `./.{app_name}/settings.json`, in-memory session). When no rule matches, the user is prompted with `Allow once` / `Allow for this session` / `Allow always for this project` / `Deny`. A filesystem grant covers the directory it names (or the directory a file is in), never the filesystem root or a directory above your home.
 
 **"Allow always" grants are user-owned, not project-owned.** They persist to
 `~/.{app_name}/project_grants.json`, keyed by the *resolved project path*, so

{agentic_cli-0.6.0 → agentic_cli-0.6.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "agentic-cli"
-version = "0.6.0"
+version = "0.6.1"
 description = "A framework for building domain-specific agentic CLI applications"
 readme = "README.md"
 license = "MIT"

{agentic_cli-0.6.0 → agentic_cli-0.6.1}/src/agentic_cli/__init__.py

@@ -105,4 +105,4 @@ __all__ = [
     "CLISettingsMixin",
 ]
 
-__version__ = "0.6.0"
+__version__ = "0.6.1"

{agentic_cli-0.6.0 → agentic_cli-0.6.1}/src/agentic_cli/cli/app.py

@@ -27,6 +27,8 @@ from agentic_cli.logging import Loggers, configure_logging
 from agentic_cli.settings_persistence import PROJECT_SETTABLE_KEYS
 
 if TYPE_CHECKING:
+    from collections.abc import Iterable
+
     from agentic_cli.settings_persistence import SettingsSaveResult
     from agentic_cli.workflow import GoogleADKWorkflowManager, EventType, WorkflowEvent
     from agentic_cli.workflow.base_manager import BaseWorkflowManager
@@ -279,9 +281,15 @@ class BaseCLIApp:
         # Sort by order and return items only
         return [item for _, item in sorted(items, key=lambda x: x[0])]
 
-    async def save_settings(self) -> "SettingsSaveResult":
+    async def save_settings(
+        self, keys: "Iterable[str] | None" = None
+    ) -> "SettingsSaveResult":
         """Save current settings, split by trust.
 
+        ``keys`` restricts the save to those fields (``/settings`` passes the
+        fields the user changed). Without it the whole live settings object is
+        saved, including values that came from the environment.
+
         Allowlisted keys go to the project config
         (./.{app_name}/settings.json). User-scoped keys differing from their
         defaults go to the user config (~/.{app_name}/settings.json), where
@@ -294,7 +302,7 @@ class BaseCLIApp:
         from agentic_cli.settings_persistence import SettingsPersistence
 
         persistence = SettingsPersistence(self._settings.app_name)
-        return persistence.save(self._settings)
+        return persistence.save(self._settings, keys=keys)
 
     @property
     def workflow(self) -> "BaseWorkflowManager":
@@ -330,9 +338,14 @@ class BaseCLIApp:
         self.should_exit = True
         self.session.exit()
 
-    async def apply_settings(self, changes: dict[str, Any]) -> None:
+    async def apply_settings(self, changes: dict[str, Any]) -> bool:
         """Apply changed settings and reinitialize workflow if needed.
 
+        All or nothing: if any value is invalid, or the workflow cannot be
+        reinitialized with the new values, every field is restored and the
+        workflow is brought back on the model it was running, so nothing
+        unusable stays in memory to be saved by ``/settings``.
+
         Settings are applied in two ways:
         1. Special settings (model, thinking_effort) use dedicated setters
            and may trigger workflow reinitialization
@@ -340,13 +353,17 @@ class BaseCLIApp:
 
         Args:
             changes: Dictionary of changed settings (key -> new_value)
+
+        Returns:
+            True if the changes were applied, False if they were rolled back.
         """
         if not changes:
             self.session.add_message("system", "No changes made.")
-            return
+            return True
 
         needs_reinit = False
         new_model = changes.get("model")
+        snapshot = _snapshot_settings(self._settings)
 
         # `orchestrator` triggers a reinit too: the controller swaps the backend
         # when it changes (otherwise the change only took effect on restart).
@@ -358,22 +375,40 @@ class BaseCLIApp:
                 if key in reinit_settings:
                     needs_reinit = True
             except ValueError as e:
+                _restore_settings(self._settings, snapshot)
                 label = key.replace("_", " ").title()
                 self.session.add_error(f"Failed to set {label}: {e}")
-                return
+                return False
 
         # Reinitialize workflow if needed
-        if needs_reinit and self._workflow_controller.is_ready:
+        controller = self._workflow_controller
+        if needs_reinit and controller.is_ready:
+            previous_model = controller.workflow.model
             try:
-                await self._workflow_controller.reinitialize(model=new_model)
+                await controller.reinitialize(model=new_model)
             except Exception as e:
-                self.session.add_error(f"Failed to reinitialize workflow: {e}")
-                return
+                _restore_settings(self._settings, snapshot)
+                self.session.add_error(
+                    f"Failed to reinitialize workflow: {e}. Settings were not changed."
+                )
+                # A failed orchestrator swap leaves the old manager running; a
+                # failed in-place reinitialize leaves it down, holding the new
+                # model. Bring it back on the model it had.
+                if not controller.is_ready:
+                    try:
+                        await controller.reinitialize(model=previous_model)
+                    except Exception as restore_error:
+                        self.session.add_error(
+                            f"Could not restart the workflow on {previous_model}: "
+                            f"{restore_error}"
+                        )
+                return False
 
         # Report changes
         for key, value in changes.items():
             label = key.replace("_", " ").title()
             self.session.add_success(f"{label}: {value}")
+        return True
 
     def _register_builtin_commands(self) -> None:
         """Register built-in commands."""
@@ -639,3 +674,23 @@ class BaseCLIApp:
 
         logger.info("app_ending")
         self.session.add_message("system", "Goodbye!")
+
+
+def _snapshot_settings(settings: BaseSettings) -> tuple[dict[str, Any], set[str]]:
+    """Capture every field value (and which were set) so a change can be undone."""
+    return dict(settings.__dict__), set(settings.__pydantic_fields_set__)
+
+
+def _restore_settings(
+    settings: BaseSettings, snapshot: tuple[dict[str, Any], set[str]]
+) -> None:
+    """Put back the values captured by :func:`_snapshot_settings`.
+
+    Written directly, like the dedicated setters do: they were valid when
+    captured, and revalidating could itself fail.
+    """
+    values, fields_set = snapshot
+    for key, value in values.items():
+        if settings.__dict__.get(key) is not value:
+            object.__setattr__(settings, key, value)
+    object.__setattr__(settings, "__pydantic_fields_set__", fields_set)

{agentic_cli-0.6.0 → agentic_cli-0.6.1}/src/agentic_cli/cli/message_processor.py

@@ -726,9 +726,17 @@ class MessageProcessor:
         first_line = lines[0]
         state.status_line = f"{icon} {tool_name}: {first_line}{duration_str}"
         style = "green" if success else "red"
-        display = f"[{style}]{icon}[/{style}] {tool_name}: {first_line}{duration_str}"
+        # Tool names and output are data: escape them, or a path such as
+        # "notes[/draft].md" is parsed as a closing tag (MarkupError, failing
+        # the turn after the tool already ran) and "[bold]" text restyles it.
+        from rich.markup import escape
+
+        display = (
+            f"[{style}]{icon}[/{style}] {escape(tool_name)}: "
+            f"{escape(first_line)}{duration_str}"
+        )
         if len(lines) > 1:
-            display += "\n" + "\n".join(lines[1:])
+            display += "\n" + escape("\n".join(lines[1:]))
         ui.add_rich(display)
 
     async def _handle_code_execution(

{agentic_cli-0.6.0 → agentic_cli-0.6.1}/src/agentic_cli/cli/settings_command.py

@@ -4,6 +4,7 @@ Uses introspection to automatically generate UI controls from Pydantic fields.
 Apps can customize which settings appear by overriding get_ui_setting_keys().
 """
 
+import inspect
 from typing import TYPE_CHECKING
 
 from thinking_prompt import SettingsDialog
@@ -52,17 +53,40 @@ class SettingsCommand(Command):
             app.session.add_message("system", "Settings unchanged.")
             return
 
-        # Apply settings changes
-        await app.apply_settings(result)
+        # Apply, then persist exactly the fields that changed. Saving the whole
+        # live object also wrote values that came from the environment or were
+        # derived at startup, making a one-run override permanent.
+        before = app.settings.model_dump()
+        if await app.apply_settings(result) is False:
+            return  # rolled back (an override returning None is still diffed)
+        after = app.settings.model_dump()
+        changed = {k for k, v in after.items() if before.get(k) != v}
+        if not changed:
+            return
 
-        # Save settings, split by trust (allowlisted → project config,
-        # user-scoped → user config)
         try:
-            saved = await app.save_settings()
-            message = f"Settings saved to {saved.project_path}"
-            if saved.user_path is not None:
-                keys = ", ".join(saved.user_scoped_keys)
-                message += f"; user-scoped ({keys}) saved to {saved.user_path}"
-            app.session.add_success(message)
+            if _accepts_keyword(app.save_settings, "keys"):
+                saved = await app.save_settings(keys=changed)
+            else:  # an app override predating keys=: its own full save
+                saved = await app.save_settings()
+            app.session.add_success(_saved_message(saved))
         except Exception as e:
             app.session.add_warning(f"Settings applied but not saved: {e}")
+
+
+def _saved_message(saved) -> str:
+    """Describe where a save landed."""
+    parts = []
+    project_keys = getattr(saved, "project_keys", None)
+    if project_keys is None or project_keys:
+        parts.append(f"Settings saved to {saved.project_path}")
+    if saved.user_path is not None:
+        keys = ", ".join(saved.user_scoped_keys)
+        parts.append(f"user-scoped ({keys}) saved to {saved.user_path}")
+    return "; ".join(parts) or "Settings saved"
+
+
+def _accepts_keyword(func, name: str) -> bool:
+    """Whether ``func`` can be called with keyword ``name``."""
+    params = inspect.signature(func).parameters.values()
+    return any(p.name == name or p.kind is p.VAR_KEYWORD for p in params)

{agentic_cli-0.6.0 → agentic_cli-0.6.1}/src/agentic_cli/config.py

@@ -49,6 +49,7 @@ from agentic_cli.settings_mixins import AppSettingsMixin, CLISettingsMixin
 # and the load-side filter below share one definition (and because the reverse
 # import would be circular). See its definition for the trust rationale.
 from agentic_cli.settings_persistence import (
+    CREDENTIAL_KEY_RE as _CREDENTIAL_KEY_RE,
     PROJECT_SETTABLE_KEYS as _PROJECT_SETTABLE_KEYS,
     get_project_config_path,
     get_user_config_path,
@@ -107,9 +108,10 @@ class _AllowlistFilterSource(PydanticBaseSettingsSource):
         return kept
 
 
-# Constructor kwargs matching this shape are credentials; an unrecognised one
-# must fail loudly instead of being swallowed by ``extra="ignore"``.
-_CREDENTIAL_KEY_RE = re.compile(r"(?i)(api_?key|secret|token|password|credential)")
+# Constructor kwargs matching _CREDENTIAL_KEY_RE (defined in
+# settings_persistence, which also uses it to never save credentials) are
+# credentials; an unrecognised one must fail loudly instead of being swallowed
+# by ``extra="ignore"``.
 
 
 def _accepted_input_names(settings_cls: Type[PydanticBaseSettings]) -> set[str]:

{agentic_cli-0.6.0 → agentic_cli-0.6.1}/src/agentic_cli/file_utils.py

@@ -4,6 +4,7 @@ import fcntl
 import json
 import os
 import re
+import secrets
 import stat
 import tempfile
 import time
@@ -128,25 +129,54 @@ def copy_regular_file_no_follow(src: Path, dst: Path) -> None:
         os.close(fd)
 
 
-def _atomic_write(path: Path, content: str) -> None:
+def _open_temp_like_a_new_file(path: Path) -> tuple[int, Path]:
+    """Create a uniquely-named temp file beside ``path``, opened for writing,
+    with the mode a plain ``open()`` would give a new file (0666 minus the
+    umask: the kernel applies it). ``mkstemp`` would force 0600."""
+    flags = os.O_WRONLY | os.O_CREAT | os.O_EXCL | getattr(os, "O_NOFOLLOW", 0)
+    for _ in range(100):
+        tmp_path = path.parent / f".{path.name}.{secrets.token_hex(6)}.tmp"
+        try:
+            return os.open(tmp_path, flags, 0o666), tmp_path
+        except FileExistsError:
+            continue
+    raise FileExistsError(f"could not create a temp file beside {path}")
+
+
+def _atomic_write(path: Path, content: str, *, preserve_mode: bool = False) -> None:
     """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.
+    - Unique temp name 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).
+    - Permissions: by default the file is private (0600), right for the
+      framework's own state. ``preserve_mode=True`` is for files the user
+      owns: an existing file keeps its permission bits and a new one gets the
+      process default, as with a plain write. Setuid/setgid are not carried
+      over (the kernel clears them when a non-root process writes a file).
     """
     path.parent.mkdir(parents=True, exist_ok=True)
-    fd, tmp_name = tempfile.mkstemp(
-        dir=str(path.parent), prefix=f".{path.name}.", suffix=".tmp"
-    )
-    tmp_path = Path(tmp_name)
+    existing = None
+    if preserve_mode:
+        try:
+            existing = stat.S_IMODE(os.stat(path).st_mode) & 0o777
+        except FileNotFoundError:
+            pass
+        fd, tmp_path = _open_temp_like_a_new_file(path)
+    else:
+        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:
+            if existing is not None:
+                os.fchmod(f.fileno(), existing)
             f.write(content)
             f.flush()
             os.fsync(f.fileno())
@@ -161,6 +191,10 @@ def atomic_write_json(path: Path, data: Any, indent: int = 2) -> None:
     _atomic_write(path, json.dumps(data, indent=indent))
 
 
-def atomic_write_text(path: Path, content: str) -> None:
-    """Write text to a file atomically."""
-    _atomic_write(path, content)
+def atomic_write_text(path: Path, content: str, *, preserve_mode: bool = False) -> None:
+    """Write text to a file atomically.
+
+    The file is private (0600) unless ``preserve_mode``: then an existing
+    file keeps its permission bits and a new one gets the process default.
+    """
+    _atomic_write(path, content, preserve_mode=preserve_mode)

agentic_cli-0.6.1/src/agentic_cli/paths.py

@@ -0,0 +1,35 @@
+"""The single interpretation of a filesystem path argument.
+
+A tool's path argument is interpreted twice: once by the permission engine
+(to decide) and once by the tool (to act). If the two interpretations ever
+differ, the engine authorizes one file while the tool touches another. Both
+therefore call :func:`resolve_path`, and nothing else.
+
+The interpretation:
+
+* ``~`` expands to the user's home directory.
+* A relative path is anchored to the process's current directory, which is
+  what the tool's own filesystem calls use.
+* ``..`` and symlinks are resolved (``Path.resolve(strict=False)``), so the
+  result is the real location, whether or not it exists yet.
+* ``${workdir}``-style placeholders are **not** expanded. They belong to rule
+  patterns (see ``workflow.permissions``), never to arguments; in an argument
+  they are ordinary characters in a directory name.
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+__all__ = ["resolve_path"]
+
+
+def resolve_path(raw: str | os.PathLike[str]) -> Path:
+    """Resolve a path argument to the absolute location a tool will act on.
+
+    Raises:
+        ValueError: if ``raw`` cannot name a path (for example it contains a
+            NUL byte).
+    """
+    return Path(raw).expanduser().resolve(strict=False)