cliver-core 0.3.0__tar.gz

cliver_core-0.3.0/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

cliver_core-0.3.0/PKG-INFO

@@ -0,0 +1,416 @@
+Metadata-Version: 2.4
+Name: cliver-core
+Version: 0.3.0
+Summary: CLIver — embeddable AgentCore library
+Keywords: ai,agents,llm,mcp,react-loop
+Author: CLIver Project
+License-Expression: Apache-2.0
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: openai>=3.0.0
+Requires-Dist: anthropic>=1.0.0
+Requires-Dist: httpx>=0.28.0
+Requires-Dist: mcp>=2.3.0,<3.0
+Requires-Dist: cliver-core[local-st] ; extra == 'local'
+Requires-Dist: cliver-core[local-flag] ; extra == 'local'
+Requires-Dist: cliver-core[local-laya] ; extra == 'local'
+Requires-Dist: flagembedding>=1.3.0 ; extra == 'local-flag'
+Requires-Dist: huggingface-hub>=0.24.0 ; extra == 'local-flag'
+Requires-Dist: laya>=0.4.0 ; extra == 'local-laya'
+Requires-Dist: sentence-transformers>=3.0 ; extra == 'local-st'
+Requires-Dist: huggingface-hub>=0.24.0 ; extra == 'local-st'
+Requires-Python: >=3.10
+Project-URL: Changelog, https://github.com/cliver-project/CLIver/blob/main/CHANGELOG.md
+Project-URL: Documentation, https://cliver-project.github.io/CLIver/
+Project-URL: Homepage, https://github.com/cliver-project/CLIver
+Project-URL: Issues, https://github.com/cliver-project/CLIver/issues
+Project-URL: Repository, https://github.com/cliver-project/CLIver
+Provides-Extra: local
+Provides-Extra: local-flag
+Provides-Extra: local-laya
+Provides-Extra: local-st
+Description-Content-Type: text/markdown
+
+# cliver-core
+
+The embeddable agent core behind [CLIver](https://github.com/cliver-project/CLIver): an agent loop
+with tool calling, per-purpose model bindings, media capabilities, and first-class MCP support.
+
+No CLI, no database, no config files — you pass Python objects in and get messages back.
+
+## Install
+
+```bash
+pip install cliver-core==0.3.0          # core library + MCP client (stdio / streamable HTTP)
+pip install "cliver-core[local]==0.3.0" # + in-process local embed / rerank / System One models
+```
+
+`0.3.0` is the first stable release of the 0.3 API series: the public API is frozen, with bug
+fixes only in `0.3.x` patch releases. Python 3.10–3.13. See
+[Stability & Versioning](https://cliver-project.github.io/CLIver/getting-started/stability/).
+
+## 0.3 highlights
+
+- Ordered binding mounts with same-purpose retryable failover
+- `run_id` correlation, `run_timeout` deadlines, and `arefresh_credentials()`
+- `chat_structured()` with pydantic / JSON-Schema validation and retries
+- Caller-supplied `context_compactor` (declarative plans) plus an opt-in `LlmCompactor`
+- System One decision models and `SystemOneSelector`
+- A streamable-HTTP MCP session pool (`session_pool_size`)
+- DashScope, Qwen, and Qwen-Image chat/media brands
+- A committed live verification suite (`make live-verify`)
+
+## Quick start
+
+```python
+import asyncio
+
+from cliver_core import AgentCore, ModelBinding, ModelBindings
+
+
+async def main():
+    agent = AgentCore(
+        ModelBindings(
+            llm=ModelBinding.llm(
+                model="deepseek-v4-flash",
+                api_key="...",
+                base_url="https://api.deepseek.com",
+            )
+        )
+    )
+    response = await agent.chat("Summarize the agent loop in one sentence.")
+    print(response.message.content)
+    await agent.aclose()
+
+
+asyncio.run(main())
+```
+
+Ready-made bindings for live-verified providers live in `cliver_core.presets`:
+
+```python
+from cliver_core import ModelBindings, presets
+
+bindings = ModelBindings(llm=presets.deepseek(api_key="..."))
+agent = AgentCore(bindings)
+```
+
+## Tools
+
+`cliver_core.tools` ships nine file, shell, todo, and web tools. Register them directly:
+
+```python
+from cliver_core.tools import discover_builtin_tools
+
+agent = AgentCore(bindings, builtin_tools=discover_builtin_tools())
+```
+
+`ToolRegistry` and the `@tool` decorator build custom tools.
+
+## Capabilities
+
+Every purpose works standalone — no AgentCore required:
+
+```python
+from cliver_core import ModelBinding
+from cliver_core.capabilities import embed, generate_image
+
+vectors = await embed(
+    texts=["hello", "world"],
+    binding=ModelBinding.embed(model="text-embedding-3-small", api_key="...", base_url="..."),
+)
+
+image = await generate_image(
+    prompt="a red panda on a skateboard",
+    binding=ModelBinding.image(model="gpt-image-1", api_key="...", base_url="..."),
+)
+```
+
+Purposes: image, video, text-to-speech, speech-to-text, embed, rerank. Long generations can return
+a `MediaJob` future via `AgentCore`'s `submit_*` variants.
+
+## Reliability and structured output
+
+`ModelBindings` accepts an ordered list per purpose. Retryable failures — rate limits, timeouts,
+connection failures, and 5xx — move to the next binding; non-retryable failures surface
+immediately. Chat is sticky after a switch, and streams switch only before the first chunk.
+
+`run_id` correlates inference, tool, and pipeline events; `run_timeout` bounds a whole run
+(preamble, model calls, tools, and handler awaits); `arefresh_credentials()` rebuilds providers
+after a credential rotation. A caller-supplied `context_compactor` can replace history once per
+loop iteration before the model call: return a `CompactionPlan` and core applies it safely, or
+return a full history as an escape hatch. `LlmCompactor` is an opt-in reference policy that is
+never installed automatically.
+
+`chat_structured()` validates a pydantic model or JSON-Schema dict and retries invalid output:
+
+```python
+from pydantic import BaseModel
+
+
+class Item(BaseModel):
+    title: str
+    price: float
+
+
+result = await agent.chat_structured("Extract the product from this page.", schema=Item)
+print(result.value.title)
+```
+
+See [Structured Output](https://cliver-project.github.io/CLIver/core-concepts/structured-output/),
+[Concurrency & Lifecycle](https://cliver-project.github.io/CLIver/core-concepts/concurrency/), and
+[Context Window](https://cliver-project.github.io/CLIver/core-concepts/context-window/).
+
+## System One
+
+`ModelBinding.system_one(...)` mounts a Jev-compatible decision model. `AgentCore.system_one()`
+answers typed `Choice` / `Score` / `Noul` questions, and `SystemOneSelector` uses the model to
+narrow tools and skills as a fail-open candidate selector. Hosted Bailian and TypeSafe presets
+and a local `laya` backend are available. See
+[System One](https://cliver-project.github.io/CLIver/core-concepts/system-one/).
+
+## Local models
+
+Run embedding, rerank, and System One decision models in-process — no endpoint. The backends
+pull torch, so they are opt-in:
+
+```bash
+pip install "cliver-core[local-st]==0.3.0"     # sentence-transformers embeddings
+pip install "cliver-core[local-flag]==0.3.0"   # FlagEmbedding embeddings + rerank
+pip install "cliver-core[local]==0.3.0"        # all three local backends
+```
+
+```python
+from cliver_core.capabilities import embed, rerank
+from cliver_core.local import (
+    LocalEmbeddingProvider,
+    LocalRerankProvider,
+    local_embed,
+    local_rerank,
+)
+
+embedder = LocalEmbeddingProvider(
+    model="BAAI/bge-base-zh-v1.5",  # Hugging Face id or local directory
+    backend="sentence-transformers",  # required; never inferred from the model name
+)
+reranker = LocalRerankProvider(
+    model="BAAI/bge-reranker-v2-m3",
+    backend="flag-embedding",
+)
+
+vectors = await embed(
+    texts=["hello", "world"],
+    binding=local_embed(provider=embedder, normalize=True),
+)
+items = await rerank(
+    query="hello",
+    documents=["hi", "hey"],
+    binding=local_rerank(provider=reranker, top_k=1),
+)
+
+await embedder.close()
+await reranker.close()
+```
+
+A provider owns one loaded model and is meant to be long-lived: create it once, share it across
+bindings and calls, and close it at shutdown. There is no process-global model cache.
+`ModelBinding.aclose()` never closes a provider you supplied.
+
+The API is deliberately explicit: `model`, `backend`, `device`, and `dtype` are parameters, not
+name-based defaults. Call options are generic — `dim` (optional output-size check), `normalize`
+(off by default; raw vectors/scores), `batch_size`, and `top_k` (rerank). Query/document prefixes
+and instruction templates belong to the application.
+
+`provider.info()` reports the resolved model directory, revision, device, dtype, and load time.
+Hugging Face downloads honor `HF_TOKEN`, `cache_dir`, `revision`, and `local_files_only`.
+
+## MCP
+
+```python
+from cliver_core.mcp import MCPClient
+
+client = MCPClient.from_discovery()  # ~/.cliver/mcp.json, .cliver/mcp.json, drop-ins
+agent = AgentCore(bindings, mcp_client=client)
+```
+
+MCP tools are advertised to the model as `mcp__<server>__<tool>`. Prompts and resources are read on
+demand — `list_prompts`, `get_prompt`, `list_resources`, `read_resource` — never registered as
+tools.
+
+## Skills
+
+[Agent Skills](https://agentskills.io/specification): a skill is a directory with a `SKILL.md`
+(frontmatter + instructions) plus optional `scripts/`, `references/`, `assets/`. cliver-core reads
+skills from **explicit sources the application supplies** — a directory of skill directories or a
+single skill directory; nothing is discovered implicitly, and later sources override earlier ones
+by name.
+
+```python
+from cliver_core import AgentCore, SkillManager
+
+skills = SkillManager(sources=["./skills"])  # routing metadata: skills.list_skills()
+agent = AgentCore(bindings, builtin_tools=[...], skill_manager=skills)
+
+result = await agent.run_skill("Refund", "订单 12345 想退货", conversation=history)
+```
+
+`run_skill` (name or an already-loaded `Skill` object) appends an activation header — skill
+name and location, so bundled `scripts/` are runnable — plus the skill body to the single
+system message and runs the normal agent loop; a declared `allowed-tools` frontmatter narrows
+the advertised tools to that set — a non-empty allowlist matching zero available tools fails
+fast, while an absent or empty list leaves tools unchanged. The other call parameters mirror
+`chat()` (except `tool_filter` and `skill_dispatch`). `run_skill()` adds none of the
+model-driven skill tools (`FindSkills`, `ActivateSkill`, `ReadSkillFile`); an `allowed-tools`
+entry naming one of those is unavailable in this path.
+
+Progressive disclosure: `list_skills()` exposes only routing metadata (name + description —
+`format_skill_catalog()` renders the catalogue for prompts); the body enters context only when a
+skill is activated; bundled files are listed (`skill.files`) and readable on demand
+(`skill.read_file("references/policy.md")`, path escapes rejected).
+
+With a `SkillManager` configured, `chat()`/`stream()` give the model that catalogue in the system
+prompt (`skill_summary_limit`, default 10), `FindSkills(query, limit)` to search the full
+catalogue, and `ActivateSkill(name)` to load a skill's body as a tool result for the rest of the
+run. Activation is one skill at a time; a declared `allowed-tools` narrows the advertised tools
+for the remaining iterations, and an activated skill that bundles files also gets
+`ReadSkillFile(path)` — confined to that skill's directory (escapes refused, UTF-8 text, 256 KiB
+cap), while workspace files stay on `Read`. Apps may rank the catalogue with
+`skill_selector(skills, user_input)`, replace lexical search with
+`skill_search(query, skills)`, and narrow both candidate pools with
+`candidate_selector(tools, skills, user_input)` / `tool_selector(tools, user_input)`.
+`run_skill()` disables dispatch for its run.
+
+The dependency-free frontmatter parser covers the spec's surface plus what cross-agent skills
+(workbuddy, accio, ...) carry — flat scalars, quoted strings, `>` / `|` blocks, and nested maps
+of any depth (unknown keys are kept in `skill.frontmatter` for forward compatibility; no anchors
+or `-` sequences). Validation follows the agentskills.io rules (name
+pattern, 64/1024/500-char limits) as load-time warnings; skills stay loadable unless `name` or
+the frontmatter itself is missing. (Anthropic's product-specific extras — reserved words in
+names — are not enforced.) Script execution sandboxes remain future work.
+
+## Pipelines
+
+`SkillPipeline` runs an ordered list of steps sequentially, each in its own fresh context. The
+caller defines the order — no LLM decides it. A step runs a skill (via `run_skill()`) or a raw
+prompt (via `chat()`); its input is composed from the original input and the prior results. A
+synthesis step is an ordinary final step that reads the earlier outputs.
+
+```python
+from cliver_core import PipelineStep, SkillPipeline
+
+
+async def log(event) -> None:
+    print(event.event, getattr(event, "step_name", None))
+
+
+pipeline = SkillPipeline(
+    [
+        PipelineStep(name="market", skill="market-analysis"),
+        PipelineStep(name="competitors", skill="competitor-scan"),
+        PipelineStep(
+            name="economics",
+            skill="unit-economics",
+            input_builder=lambda ctx: f"{ctx.input}\n\nMarket:\n{ctx.result('market').content}",
+        ),
+        PipelineStep(
+            name="report",
+            skill="report-writing",
+            input_builder=lambda ctx: (
+                "\n\n".join(f"## {r.name}\n{r.content}" for r in ctx.results) + f"\n\n## Idea\n{ctx.input}"
+            ),
+        ),
+    ],
+    agent=agent,
+    on_event=log,  # pipeline lifecycle + forwarded tool events
+)
+
+result = await pipeline.run("A subscription box for office plants")
+print(result.ok, result.final.content)
+```
+
+- **Results** — `PipelineResult.results` is an ordered tuple of `StepResult`s
+  (`name`, `content`, optional `metadata`, `usage`, `error`); `.final` is the last result and
+  `.ok` is true only when every step ran and none failed.
+- **Input builders** — `PipelineContext` carries the original `input` and prior `results`
+  (`ctx.result(name)`, `ctx.previous`). Builders may be sync or async. The default input is the
+  pipeline input.
+- **Step prompts** — `PipelineStep.prompt` is raw step instructions appended to the single
+  system message (as extra instructions alongside a skill, or as the whole instruction when no
+  skill is given).
+- **Failure policy** — `on_failure=FailurePolicy.STOP` (default) stops at the first failed step
+  and sets `PipelineResult.stopped`; `FailurePolicy.CONTINUE` records the error and runs the
+  next step. Later steps can inspect `ctx.result(name).error`.
+- **Runners** — a step may inject a `runner(step, step_input, context, emit)` to use a different
+  `AgentCore` instance, model, tools, or skill set; pass `on_event=emit` so its tool events are
+  forwarded. Custom runners may return `StepOutput` (content + metadata + usage),
+  `CLIverResponse`, or a plain string.
+- **Events** — the pipeline emits `PipelineEvent`s (`pipeline.start`, `pipeline.step_start`,
+  `pipeline.step_end`, `pipeline.step_error`, `pipeline.end`) and forwards each step's
+  `ToolEvent`s. Cancelling the task emits `pipeline.end` with `{"cancelled": true}` and
+  re-raises `CancelledError`.
+
+## Permissions & execution policy
+
+Two independent axes, both opt-in — with neither set, every tool runs exactly as before.
+
+**Permission axis (may this tool run?).** Every tool carries a category: `SAFE` or `ASK`.
+Read-only builtins (`Read`, `LS`, `Grep`, `TodoRead`/`TodoWrite`) are `SAFE`; mutating ones
+(`Write`, `Bash`, `Exec`, `WebFetch`) are `ASK` by default. MCP tools map the spec's
+self-declared `readOnlyHint` annotation to `SAFE` — a hint, never a permission boundary.
+An application-supplied async `permission_callback` is consulted before any `ASK` tool runs:
+
+```python
+from cliver_core import AgentCore, Decision, EnvSpec, ExecutionPolicy, SAFE_ENV_VARS, ToolCategory
+
+
+async def ask_user(ctx) -> Decision:  # ctx: tool_name, args, server, category
+    answer = await my_ui.confirm(f"Run {ctx.tool_name}?")
+    return Decision.allow() if answer else Decision.deny("user said no")
+
+
+agent = AgentCore(
+    bindings,
+    builtin_tools=[...],
+    permission_callback=ask_user,  # None → ASK tools run unchecked
+    execution_policy=ExecutionPolicy(  # environment axis, ambient per call
+        env=EnvSpec(mode="allowlist", names=set(SAFE_ENV_VARS)),
+        cwd=project_root,
+        write_paths=[project_root / "src"],
+    ),
+    safety_overrides={"mcp__github__create_issue": ToolCategory.ASK},
+)
+```
+
+A denial never raises: it returns `{"error": "Permission denied: …", "denied": true}` to the
+model through the normal tool-result path and also emits `ToolEventType.PERMISSION_DENIED`
+through `on_event` before the call's `TOOL_END`. Callback exceptions fail closed. Denials share
+the consecutive cap with errors (5 in a row stops the loop). `safety_overrides` reclassify
+individual tools per AgentCore instance — builtins are shared singletons and never mutated.
+
+**Environment axis (where does it run, what does it see?).** Pass `execution_policy=` to the
+constructor or per `chat()`/`stream()` call (call-site wins). While ambient: `Bash` and `Exec`
+run with the policy env (`allowlist`/`denylist`/inherit) and pinned cwd — `Bash` logs an INFO
+line when the pin overrides its `directory` argument; `Read`/`LS`/`Grep`/`Write` enforce
+`read_paths`/`write_paths` (resolved against the policy cwd, symlinks followed). `run_skill`
+applies a call-site policy verbatim; otherwise an agent-level policy is reused with cwd pinned
+to the skill's directory.
+
+The two axes are complementary, not a hard sandbox: `read_paths`/`write_paths` bind the file
+tools only — an approved `Bash`/`Exec` call runs as your process user and can touch anything
+that user can, under the filtered env and pinned working directory. Use the permission axis
+(callback, `safety_overrides`) to decide whether shell access is granted at all; the paths are
+a guardrail against accidental access, not an OS-level confinement.
+
+## License
+
+Apache-2.0