Release v0.6.0 — jobs, durable sessions, security hardening, and framework correctness

[shoom1]

Release v0.6.0 — develop → main. 158 commits (129 non-merge) since v0.5.3, 194 files, +29,511 / −3,428.

The headline is not a single feature: it is that long-running work, conversation state, and the sandbox all became durable and hardened at once, and that a framework-wide correctness pass closed a long tail of identity, lifecycle and cross-process defects. Five P0 security fixes ship here that are not in v0.5.3.

Major features

• Long-running jobs, end to end. An internal JobManager over pluggable execution backends (subprocess, inprocess), restart-safe completion via an on-disk exit_code sentinel, a concurrency cap and queue, a /jobs command, and a background JobMonitor that advances detached jobs with no LLM turn. When a job that opted in finishes, the agent is auto-resumed with its result (job_auto_resume, default off; /resume on demand).
• Durable sessions by default. Conversations persist continuously through each orchestrator's native store — ADK via DatabaseSessionService, LangGraph via a persistent checkpointer — keyed by session id. session_store selects sqlite (default), postgres, or memory. --session <id> resumes; /sessions lists and deletes. Persistence is per-event and full-fidelity, so it survives a crash mid-turn and keeps function-call ids intact.
• Docker sandbox backend for sandbox_execute, with a dedicated CI job that fails rather than skips when a runtime is missing.
• Stateful executor toolset and the report-writer skill, including compile_document for LaTeX output.
• Release acceptance coverage — headless application composition, a real-terminal PTY smoke, and a built-wheel job that installs the artifact and drives the installed research-demo console script.

Security

Five P0 fixes plus the fail-closed permission hardening:

• P0-1 — project config can no longer flip security boundaries. A cloned repo's ./.{app}/settings.json (and a cwd-relative .env) is restricted to an explicit deny-by-default allowlist; security-sensitive keys are dropped with a warning. Interactive "Allow always" grants moved out of the repository to ~/.{app}/project_grants.json, keyed by resolved project path.
• P0-2 — sandbox file transfer is symlink-safe. Staging and collection refuse to follow symlinks (copy_regular_file_no_follow), outputs are 0700. O_NOFOLLOW guards only the final component, so the parent directory is lstated too.
• P0-3 — compile_document host execution is contained. Private temp build dir, exact TEXMF allowlist, anchored source filename, RLIMIT_FSIZE/RLIMIT_CPU, bounded captured output, SIGKILL on timeout.
• P0-4 — glob/grep are contained to the authorized root. Patterns cannot escape it, ceilings apply before the walk, and truncation is reported instead of silently returning a partial answer.
• P0-5 — web_fetch cannot reach internal networks. A PinnedTransport resolves every A/AAAA record up front, rejects if any is non-global (including NAT64 and 6to4-relay forms), then connects to the validated IP with sni_hostname so TLS still binds to the hostname — closing the DNS-rebinding window. Redirects and robots.txt use the same transport; bodies are capped while streaming.
• P1-7 — the permission engine fails closed. A missing engine denied nothing; it now denies. Tool identity is resolved by the object the registry issued, never by name — an unregistered callable named after a genuine tool no longer inherits its capabilities.

ADK multi-agent delegation repaired

Two defects made ADK's built-in agent hand-off unusable, so any app declaring sub_agents could not delegate at all.

1. PermissionPlugin unwraps .func only for exact ADK function-tool types, and ADK's auto-injected TransferToAgentTool is a FunctionTool subclass — so the routing tool resolved to no registry identity and was denied as unregistered, even with permissions disabled. Its exact class is now trusted on the same terms as the others; every other subclass, forged object and same-named tool stays denied, and no name-based authority was restored.
2. ADK builds the tool's model-visible description from transfer_to_agent's docstring, which through 1.37.0 advises callers to "use TransferToAgentTool instead of this function directly" — guidance meant for Python callers that led models to emit the class name, which ADK then rejects. A narrowly scoped before-model plugin corrects that description on the prepared request, only for the exact native tool and only while the misleading text is present. It is idempotent and becomes a no-op on any ADK release shipping a corrected docstring (fixed upstream in 2.x).

Breaking changes and migration

Change	Migration
ToolRegistry.register() raises on duplicate names	Two tools sharing a name must use declare_tool + register_tool(..., variant_of=...); previously the last import silently won
Tools in a non-default ToolRegistry are not framework-issued	They pass through assembly untouched and are denied by the permission engine — register framework tools in the default registry
Session hooks take user_id	session_exists/list_sessions/delete_session/recent_messages/load_session/save_session gain an optional keyword; overrides that never added it keep working
Backends without a durable store	supports_sessions is False and base hooks raise NotImplementedError instead of answering False/[]
MessageProcessor.process() returns TurnResult	Switch on TurnResult.status; CANCELLED and FAILED were previously indistinguishable
Agent graphs validated up front	Duplicate names, dangling/self sub_agents, cycles, shared children and more than one root raise AgentGraphError
Prompt factories	Zero args or exactly one settings arg; async def and non-string returns are rejected
skill_scripts_enabled removed	run_skill_script is exposed exactly when make_skill_toolset is given a code executor
BaseWorkflowManager._TOOL_SERVICE_MAP removed	Use @register_tool(..., requires="kb_manager")
Legacy JSON session snapshots removed	Superseded by the native durable stores; no migration of old JSON sessions
JobRecord.resumed	Now a read-only property; the field is resume_state (pending → resuming → delivered|failed)
ALLOW_ALWAYS_CHOICE value changed	Now "Allow always for this project"; the former response wording is still parsed, so no behavioural change

BaseSettings(google_api_key=...) now actually binds — it silently bound nothing before, so workarounds can be simplified, and a misspelled credential kwarg is now an error rather than being dropped.

Verification

Deterministic (offline): the full offline suite is green — 2415 passed, 9 skipped, 34 deselected, 26 xfailed. compileall, pip check and git diff --check clean at the tip and per commit.

PTY: the real console process is driven over a pty through startup → /help → /exit, asserting no traceback and exit 0, with no API key, network, Docker or LLM. The session is also asserted side-effect free.

Built wheel: a dedicated CI job builds the wheel, installs it into a throwaway virtualenv and runs the same session through the installed research-demo console script, confirming the child resolves inside the venv (not the checkout), that the packaged data files ship (benchmarks.csv, the report-writer SKILL.md, report_template.tex), and that the declared version reaches the wheel filename, the installed distribution metadata and agentic_cli.__version__. The version is derived from pyproject.toml, not hardcoded.

Docker: the isolation job runs against a real container runtime and fails rather than skips when one is missing.

Live research demo (-m llm, ADK, gemini-2.5-flash — the shipped default, isolated from developer config): three independent runs, no retries, all three behavioural contracts green in each — explicit planning, bounded arXiv delegation with a successful search_arxiv, and KB ingest → readback over a persistent session. gemini-3.1-pro-preview — the model that originally emitted the class name — also passes delegation; it is not the default and nothing is pinned to it.

Known limitations

• Job-result resume is ADK-only. The coordinator and association layer are backend-agnostic, but resume_with_job_result is implemented for ADK; LangGraph resume is not wired.
• The non-CLI backend-exception contract is unresolved. A model that invents a tool name surfaces as an exception out of process(). The CLI catches it and renders a workflow error, but every non-CLI consumer inherits an undocumented contract. Whether process() should propagate backend exceptions or convert them to fatal WorkflowEvent.ERROR events is a deliberate post-0.6 decision.
• LangGraph is in maintenance. It remains supported and tested, but new capability work (model provisioning, job resume) is ADK-first.
• Third-party job backends are polled by every observing manager, and only an UNKNOWN poll answer is filtered — a backend returning a wrong non-UNKNOWN state is still trusted.
• InProcessBackend.close() lets queued work finish, so a long backlog delays interpreter exit rather than being silently discarded.

Publication is manual

There is no publish workflow in this repository — CI runs tests only. Merging this PR and tagging does not build or upload a package anywhere. Building and publishing the 0.6.0 artifact to any index is a separate, manual step, and tagging should follow the existing convention (tag on main after the merge).

https://claude.ai/code/session_01BpktWb9vKN5exdT9MbLQYh