corecoder 0.4.2__tar.gz → 0.5.0__tar.gz

{corecoder-0.4.2 → corecoder-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: corecoder
-Version: 0.4.2
+Version: 0.5.0
 Summary: Minimal AI coding agent (~1,000 lines of Python) inspired by Claude Code. Works with any LLM. (formerly NanoCoder)
 Project-URL: Homepage, https://github.com/he-yufeng/CoreCoder
 Project-URL: Repository, https://github.com/he-yufeng/CoreCoder
@@ -37,7 +37,7 @@ Description-Content-Type: text/markdown
 
 # CoreCoder
 
-**The nanoGPT of coding agents. 1,201 lines of pure Python — understand how a coding agent actually works, then fork your own.**
+**The nanoGPT of coding agents. 1,217 lines of pure Python — understand how a coding agent actually works, then fork your own.**
 
 *learn from it · fork it · ship something better*
 
@@ -47,7 +47,7 @@ Description-Content-Type: text/markdown
 [![Python](https://img.shields.io/badge/python-3.10+-blue)](https://python.org)
 [![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)
 [![Tests](https://github.com/he-yufeng/CoreCoder/actions/workflows/ci.yml/badge.svg)](https://github.com/he-yufeng/CoreCoder/actions)
-[![engine](https://img.shields.io/badge/engine-1201_LoC-blue)](article/00-index_EN.md)
+[![engine](https://img.shields.io/badge/engine-1217_LoC-blue)](article/00-index_EN.md)
 [![essays](https://img.shields.io/badge/source--reading-8_bilingual-orange)](article/00-index_EN.md)
 
 </div>
@@ -60,7 +60,7 @@ Description-Content-Type: text/markdown
 
 | | CoreCoder | Claude Code | aider | nanoGPT |
 |---|---|---|---|---|
-| Lines of code | ~1,201 engine / 2,008 total | hundreds of thousands (closed) | tens of thousands of Python | ~600 (two files) |
+| Lines of code | ~1,217 engine / 2,107 total | hundreds of thousands (closed) | tens of thousands of Python | ~600 (two files) |
 | Time to read it all | one afternoon | can't (closed) | a few days of slogging | one afternoon |
 | Breakpoint, change, rerun? | yes, every line | no | yes, but there's a lot | yes |
 | What it's for | understand one, then fork your own | production coding assistant | terminal pair-programming | minimal GPT for teaching |
@@ -71,9 +71,9 @@ The nanoGPT column is there as a reference point: minimal, readable, but it teac
 
 I've always felt coding agents get talked about as if they were arcane. Strip a tool like Claude Code or Cursor all the way down and the core is a `while` loop wrapped around a large model, plus seven or eight tools that let it actually do things. The hard part was never the loop; it's everything the loop has to cope with once it meets the real world. CoreCoder is the minimal version that writes that core out honestly.
 
-The engine (loop, model interface, context, tools, sessions) is 1,201 lines once you drop blank lines and comments. Counting the outer CLI, config and packaging too, the whole package is 21 files: 2,008 physical lines, 1,614 net, every one short enough to read in a single sitting.
+The engine (loop, model interface, context, tools, sessions) is 1,217 lines once you drop blank lines and comments. Counting the outer CLI, config and packaging too, the whole package is 22 files: 2,107 physical lines, 1,697 net, every one short enough to read in a single sitting.
 
-And it really runs: reads and writes files, executes shell, spawns sub-agents, compacts context in three tiers, and tells you the tokens and dollars a run burned whenever you ask. 103 tests, all green. But the point of it running isn't to become your daily driver. It runs so the walkthrough can't lie: a reference that shows how an agent works has to actually work.
+And it really runs: reads and writes files, executes shell, spawns sub-agents, compacts context in three tiers, and tells you the tokens and dollars a run burned whenever you ask. Anything that would mutate your disk or run a command stops for your consent first. 119 tests, all green. But the point of it running isn't to become your daily driver. It runs so the walkthrough can't lie: a reference that shows how an agent works has to actually work.
 
 The code came out of a public teardown: open analyses have already exposed a lot of the load-bearing architecture inside production agents like Claude Code. I took the most essential layer and rewrote it honestly, in as little code as I could. So reading CoreCoder is roughly like reading a runnable, annotated take on how that kind of agent works, except it's only a minimal reimplementation, sitting right there on your machine for you to take apart and change.
 
@@ -120,12 +120,13 @@ Laid out flat, the whole project is this big. Skim it before you clone and you'l
 
 ```
 corecoder/
-├── agent.py        agent loop + parallel tool exec       162 lines   ← start here
+├── agent.py        agent loop + parallel tool exec       180 lines   ← start here
 ├── llm.py          streaming client + retry + cost        336 lines
 ├── context.py      three-tier context compaction          210 lines
 ├── session.py      save / resume + path-traversal guard    97 lines
+├── permissions.py  consent for mutating tools              48 lines
 ├── prompt.py       system prompt                           33 lines
-├── cli.py          REPL + slash commands + one-shot       270 lines
+├── cli.py          REPL + slash commands + one-shot       317 lines
 ├── config.py       env-var config                          57 lines
 └── tools/
     ├── bash.py       shell + dangerous-command gate + cd  127 lines
@@ -135,7 +136,7 @@ corecoder/
     ├── read.py       file read                             53 lines
     ├── write.py      file write                            38 lines
     ├── todo.py       agent-maintained task checklist       79 lines
-    ├── agent.py      sub-agent spawning                    58 lines
+    ├── agent.py      sub-agent spawning                    63 lines
     └── base.py       tool base class                       27 lines
 ```
 
@@ -226,6 +227,14 @@ quit / exit      exit (Ctrl+C cancels the current round)
 
 Session IDs are sanitized to safe characters before they become filenames, every archive lands under `~/.corecoder/sessions`, and a malicious session name can't traverse out.
 
+## Permissions
+
+Read-only tools (`read_file`, `glob`, `grep`, `todo_write`) run the moment the model asks. The mutating ones (`edit_file`, `write_file`, `bash`, and spawning a sub-agent) stop for consent first, and the REPL banner shows which mode you're in:
+
+- In the REPL you get one prompt per call: allow once, always allow this tool, or deny. "Always" is remembered per tool for the rest of the session, and a sub-agent inherits the same layer, so consent follows the work wherever it happens.
+- In one-shot mode (`-p`) there is nobody to ask, so a mutating call is refused on the spot and the refusal goes back to the model as an ordinary tool result: the loop never hangs on input that can't arrive. Pass `--yes` to approve everything up front (scripts, CI).
+- The decision itself is pure logic in `permissions.py`, with the terminal only supplying the prompt callback. You can unit-test consent without a TTY, or reuse the layer in your own embedding.
+
 ## Related Projects
 
 If working through CoreCoder was useful, here are a few other tools I've built around agents and LLM systems:
@@ -238,7 +247,7 @@ If working through CoreCoder was useful, here are a few other tools I've built a
 
 ## Contributing / License
 
-Before you send anything, run `pytest tests/ -q` (103 tests), `ruff check`, and `compileall`, and make sure they're green. MIT licensed: fork it, learn from it, ship something better. A mention of this project is appreciated.
+Before you send anything, run `pytest tests/ -q` (119 tests), `ruff check`, and `compileall`, and make sure they're green. MIT licensed: fork it, learn from it, ship something better. A mention of this project is appreciated.
 
 ---
 

{corecoder-0.4.2 → corecoder-0.5.0}/README.md

@@ -2,7 +2,7 @@
 
 # CoreCoder
 
-**The nanoGPT of coding agents. 1,201 lines of pure Python — understand how a coding agent actually works, then fork your own.**
+**The nanoGPT of coding agents. 1,217 lines of pure Python — understand how a coding agent actually works, then fork your own.**
 
 *learn from it · fork it · ship something better*
 
@@ -12,7 +12,7 @@
 [![Python](https://img.shields.io/badge/python-3.10+-blue)](https://python.org)
 [![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)
 [![Tests](https://github.com/he-yufeng/CoreCoder/actions/workflows/ci.yml/badge.svg)](https://github.com/he-yufeng/CoreCoder/actions)
-[![engine](https://img.shields.io/badge/engine-1201_LoC-blue)](article/00-index_EN.md)
+[![engine](https://img.shields.io/badge/engine-1217_LoC-blue)](article/00-index_EN.md)
 [![essays](https://img.shields.io/badge/source--reading-8_bilingual-orange)](article/00-index_EN.md)
 
 </div>
@@ -25,7 +25,7 @@
 
 | | CoreCoder | Claude Code | aider | nanoGPT |
 |---|---|---|---|---|
-| Lines of code | ~1,201 engine / 2,008 total | hundreds of thousands (closed) | tens of thousands of Python | ~600 (two files) |
+| Lines of code | ~1,217 engine / 2,107 total | hundreds of thousands (closed) | tens of thousands of Python | ~600 (two files) |
 | Time to read it all | one afternoon | can't (closed) | a few days of slogging | one afternoon |
 | Breakpoint, change, rerun? | yes, every line | no | yes, but there's a lot | yes |
 | What it's for | understand one, then fork your own | production coding assistant | terminal pair-programming | minimal GPT for teaching |
@@ -36,9 +36,9 @@ The nanoGPT column is there as a reference point: minimal, readable, but it teac
 
 I've always felt coding agents get talked about as if they were arcane. Strip a tool like Claude Code or Cursor all the way down and the core is a `while` loop wrapped around a large model, plus seven or eight tools that let it actually do things. The hard part was never the loop; it's everything the loop has to cope with once it meets the real world. CoreCoder is the minimal version that writes that core out honestly.
 
-The engine (loop, model interface, context, tools, sessions) is 1,201 lines once you drop blank lines and comments. Counting the outer CLI, config and packaging too, the whole package is 21 files: 2,008 physical lines, 1,614 net, every one short enough to read in a single sitting.
+The engine (loop, model interface, context, tools, sessions) is 1,217 lines once you drop blank lines and comments. Counting the outer CLI, config and packaging too, the whole package is 22 files: 2,107 physical lines, 1,697 net, every one short enough to read in a single sitting.
 
-And it really runs: reads and writes files, executes shell, spawns sub-agents, compacts context in three tiers, and tells you the tokens and dollars a run burned whenever you ask. 103 tests, all green. But the point of it running isn't to become your daily driver. It runs so the walkthrough can't lie: a reference that shows how an agent works has to actually work.
+And it really runs: reads and writes files, executes shell, spawns sub-agents, compacts context in three tiers, and tells you the tokens and dollars a run burned whenever you ask. Anything that would mutate your disk or run a command stops for your consent first. 119 tests, all green. But the point of it running isn't to become your daily driver. It runs so the walkthrough can't lie: a reference that shows how an agent works has to actually work.
 
 The code came out of a public teardown: open analyses have already exposed a lot of the load-bearing architecture inside production agents like Claude Code. I took the most essential layer and rewrote it honestly, in as little code as I could. So reading CoreCoder is roughly like reading a runnable, annotated take on how that kind of agent works, except it's only a minimal reimplementation, sitting right there on your machine for you to take apart and change.
 
@@ -85,12 +85,13 @@ Laid out flat, the whole project is this big. Skim it before you clone and you'l
 
 ```
 corecoder/
-├── agent.py        agent loop + parallel tool exec       162 lines   ← start here
+├── agent.py        agent loop + parallel tool exec       180 lines   ← start here
 ├── llm.py          streaming client + retry + cost        336 lines
 ├── context.py      three-tier context compaction          210 lines
 ├── session.py      save / resume + path-traversal guard    97 lines
+├── permissions.py  consent for mutating tools              48 lines
 ├── prompt.py       system prompt                           33 lines
-├── cli.py          REPL + slash commands + one-shot       270 lines
+├── cli.py          REPL + slash commands + one-shot       317 lines
 ├── config.py       env-var config                          57 lines
 └── tools/
     ├── bash.py       shell + dangerous-command gate + cd  127 lines
@@ -100,7 +101,7 @@ corecoder/
     ├── read.py       file read                             53 lines
     ├── write.py      file write                            38 lines
     ├── todo.py       agent-maintained task checklist       79 lines
-    ├── agent.py      sub-agent spawning                    58 lines
+    ├── agent.py      sub-agent spawning                    63 lines
     └── base.py       tool base class                       27 lines
 ```
 
@@ -191,6 +192,14 @@ quit / exit      exit (Ctrl+C cancels the current round)
 
 Session IDs are sanitized to safe characters before they become filenames, every archive lands under `~/.corecoder/sessions`, and a malicious session name can't traverse out.
 
+## Permissions
+
+Read-only tools (`read_file`, `glob`, `grep`, `todo_write`) run the moment the model asks. The mutating ones (`edit_file`, `write_file`, `bash`, and spawning a sub-agent) stop for consent first, and the REPL banner shows which mode you're in:
+
+- In the REPL you get one prompt per call: allow once, always allow this tool, or deny. "Always" is remembered per tool for the rest of the session, and a sub-agent inherits the same layer, so consent follows the work wherever it happens.
+- In one-shot mode (`-p`) there is nobody to ask, so a mutating call is refused on the spot and the refusal goes back to the model as an ordinary tool result: the loop never hangs on input that can't arrive. Pass `--yes` to approve everything up front (scripts, CI).
+- The decision itself is pure logic in `permissions.py`, with the terminal only supplying the prompt callback. You can unit-test consent without a TTY, or reuse the layer in your own embedding.
+
 ## Related Projects
 
 If working through CoreCoder was useful, here are a few other tools I've built around agents and LLM systems:
@@ -203,7 +212,7 @@ If working through CoreCoder was useful, here are a few other tools I've built a
 
 ## Contributing / License
 
-Before you send anything, run `pytest tests/ -q` (103 tests), `ruff check`, and `compileall`, and make sure they're green. MIT licensed: fork it, learn from it, ship something better. A mention of this project is appreciated.
+Before you send anything, run `pytest tests/ -q` (119 tests), `ruff check`, and `compileall`, and make sure they're green. MIT licensed: fork it, learn from it, ship something better. A mention of this project is appreciated.
 
 ---
 

{corecoder-0.4.2 → corecoder-0.5.0}/README_CN.md

@@ -2,7 +2,7 @@
 
 # CoreCoder
 
-**编程 agent 里的 nanoGPT。1201 行纯 Python，读懂一个 coding agent 到底怎么运作，再 fork 出你自己的。**
+**编程 agent 里的 nanoGPT。1217 行纯 Python，读懂一个 coding agent 到底怎么运作，再 fork 出你自己的。**
 
 *learn from it · fork it · ship something better*
 
@@ -12,7 +12,7 @@
 [![Python](https://img.shields.io/badge/python-3.10+-blue)](https://python.org)
 [![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)
 [![Tests](https://github.com/he-yufeng/CoreCoder/actions/workflows/ci.yml/badge.svg)](https://github.com/he-yufeng/CoreCoder/actions)
-[![engine](https://img.shields.io/badge/engine-1201_LoC-blue)](article/)
+[![engine](https://img.shields.io/badge/engine-1217_LoC-blue)](article/)
 [![源码导读](https://img.shields.io/badge/源码导读-8篇双语-orange)](article/)
 
 </div>
@@ -25,7 +25,7 @@
 
 | | CoreCoder | Claude Code | aider | nanoGPT |
 |---|---|---|---|---|
-| 代码量 | 引擎约 1201 行 / 整包 2008 行 | 几十万行（闭源） | 数万行 Python | 约 600 行（两个文件） |
+| 代码量 | 引擎约 1217 行 / 整包 2107 行 | 几十万行（闭源） | 数万行 Python | 约 600 行（两个文件） |
 | 读完要多久 | 一个下午 | 读不了（闭源） | 得啃几天 | 一个下午 |
 | 能不能下断点改了再跑 | 能，每一行 | 不能 | 能，但量大 | 能 |
 | 定位 | 读懂并 fork 出你自己的 agent | 生产级编程助手 | 终端结对编程 | 教学用最小 GPT |
@@ -36,9 +36,9 @@ nanoGPT 那一列是拿来对照的：它最小、可读，但教的是训一个
 
 我一直觉得 coding agent 被讲得太玄了。把 Claude Code、Cursor 这类工具扒到底，核心是一个 while 循环套着一个大模型，外加七八个让它能真正动手的工具。难的从来不是这个循环，而是循环跑进真实世界以后要兜的那些底。CoreCoder 就是把这个核心老老实实写出来的最小版本。
 
-引擎部分（循环、模型接口、上下文、工具、会话）去掉空行和注释是 1201 行。连最外层的 CLI、配置、打包一起算，整个包 21 个文件、物理 2008 行、净 1614 行，每个文件都短到能一口气读完。
+引擎部分（循环、模型接口、上下文、工具、会话）去掉空行和注释是 1217 行。连最外层的 CLI、配置、打包一起算，整个包 22 个文件、物理 2107 行、净 1697 行，每个文件都短到能一口气读完。
 
-它真能跑：读写文件、执行 shell、派子 agent、分三层压上下文，还能随时把这趟烧掉的 token 和美元数报给你，103 个测试是绿的。但能跑不是为了劝你拿去日用，而是为了让这份「注释」不撒谎：一个解释 agent 怎么运作的范例，自己得真能运作。
+它真能跑：读写文件、执行 shell、派子 agent、分三层压上下文，还能随时把这趟烧掉的 token 和美元数报给你。任何要动你磁盘、要跑命令的调用，都会先停下来等你点头，119 个测试是绿的。但能跑不是为了劝你拿去日用，而是为了让这份「注释」不撒谎：一个解释 agent 怎么运作的范例，自己得真能运作。
 
 代码来自一次公开拆解。公开的源码分析里，Claude Code 这类生产级 agent 暴露出不少关键架构，我挑出最核心的一层，用尽量少的代码诚实地复写了一遍。所以读 CoreCoder，约等于读一份基于公开源码分析的「可运行注释版」：讲的是这类 agent 的核心思路，而它本身只是最小复写，就摆在你机器上，随你拆、随你改。
 
@@ -85,12 +85,13 @@ corecoder -p "给 parse_config() 加错误处理"   # 一次性模式，干完
 
 ```
 corecoder/
-├── agent.py        agent 主循环 + 并行工具执行       162 行   ← 从这里开始读
+├── agent.py        agent 主循环 + 并行工具执行       180 行   ← 从这里开始读
 ├── llm.py          流式客户端 + 重试 + 成本统计       336 行
 ├── context.py      三层上下文压缩                     210 行
 ├── session.py      会话存盘 / 续聊 + 路径穿越防护      97 行
+├── permissions.py  改动类工具的用户授权                48 行
 ├── prompt.py       系统提示词                          33 行
-├── cli.py          REPL + 斜杠命令 + 一次性模式        270 行
+├── cli.py          REPL + 斜杠命令 + 一次性模式        317 行
 ├── config.py       环境变量配置                        57 行
 └── tools/
     ├── bash.py       shell + 危险命令闸 + cd 追踪      127 行
@@ -100,7 +101,7 @@ corecoder/
     ├── read.py       文件读取                           53 行
     ├── write.py      文件写入                           38 行
     ├── todo.py       agent 自维护的任务清单            79 行
-    ├── agent.py      子 agent 派生                      58 行
+    ├── agent.py      子 agent 派生                      63 行
     └── base.py       工具基类                           27 行
 ```
 
@@ -191,6 +192,14 @@ quit / exit      退出（Ctrl+C 取消当前回合）
 
 会话 ID 会先清洗成安全字符再拿去当文件名，存档统统落在 `~/.corecoder/sessions` 里，恶意会话名穿越不出去。
 
+## 权限
+
+只读工具（`read_file`、`glob`、`grep`、`todo_write`）模型一调就跑。会动手的那些（`edit_file`、`write_file`、`bash`，以及派生子 agent）先停下来等你点头，REPL 启动横幅里能看到当前是哪种模式：
+
+- REPL 里每次调用问一次：允许这一次、本工具本次会话都允许、或者拒绝。「都允许」按工具记到会话结束；子 agent 继承同一层授权，活走到哪，许可跟到哪。
+- 一次性模式（`-p`）没人可问，改动类调用当场被拒，拒绝理由作为普通工具结果回给模型：循环绝不会卡在等一个永远不会来的输入上。要全部预授权就加 `--yes`（脚本、CI 场景）。
+- 判断本身是 `permissions.py` 里的纯逻辑，终端只是塞进来一个提问回调。不用 TTY 也能单测授权逻辑，或者直接搬进你自己的嵌入场景。
+
 ## 相关项目
 
 如果你读 CoreCoder 读得还顺，下面几个我做的 agent / LLM 系统方向的工具也许用得上：
@@ -203,7 +212,7 @@ quit / exit      退出（Ctrl+C 取消当前回合）
 
 ## 贡献 / License
 
-动手之前先跑一遍 `pytest tests/ -q`（103 个测试）、`ruff check` 和 `compileall`，绿了再提。MIT License，欢迎 fork 拿去造更好的东西，能在 README 里留一句出处就更好。
+动手之前先跑一遍 `pytest tests/ -q`（119 个测试）、`ruff check` 和 `compileall`，绿了再提。MIT License，欢迎 fork 拿去造更好的东西，能在 README 里留一句出处就更好。
 
 ---
 

{corecoder-0.4.2 → corecoder-0.5.0}/corecoder/__init__.py

@@ -1,6 +1,6 @@
 """CoreCoder - Minimal AI coding agent inspired by Claude Code's architecture."""
 
-__version__ = "0.4.2"
+__version__ = "0.5.0"
 
 from corecoder.agent import Agent
 from corecoder.config import Config

{corecoder-0.4.2 → corecoder-0.5.0}/corecoder/agent.py

@@ -28,9 +28,11 @@ class Agent:
         tools: list[Tool] | None = None,
         max_context_tokens: int = 128_000,
         max_rounds: int = 50,
+        permission=None,
     ):
         self.llm = llm
         self.tools = tools if tools is not None else ALL_TOOLS
+        self.permission = permission
         self._tool_by_name = {t.name: t for t in self.tools}
         self.messages: list[dict] = []
         self.context = ContextManager(max_tokens=max_context_tokens)
@@ -83,7 +85,7 @@ class Agent:
                     tc = resp.tool_calls[0]
                     if on_tool:
                         on_tool(tc.name, tc.arguments)
-                    result = self._exec_tool(tc)
+                    result = self._permit(tc) or self._exec_tool(tc)
                     self.messages.append({
                         "role": "tool",
                         "tool_call_id": tc.id,
@@ -109,6 +111,13 @@ class Agent:
 
         return "(reached maximum tool-call rounds)"
 
+    def _permit(self, tc) -> str | None:
+        """Consent check for one call. None means go ahead; a string is the
+        refusal, returned as the tool result instead of executing."""
+        if self.permission is None:
+            return None
+        return self.permission.check(tc.name, tc.arguments)
+
     def _exec_tool(self, tc) -> str:
         """Execute a single tool call, returning the result string."""
         tool = self._tool_by_name.get(tc.name)
@@ -137,9 +146,18 @@ class Agent:
             if on_tool:
                 on_tool(tc.name, tc.arguments)
 
+        # consent is settled up front on this thread: prompting from pool
+        # workers would interleave several prompts on one terminal
+        results = [self._permit(tc) for tc in tool_calls]
         with concurrent.futures.ThreadPoolExecutor(max_workers=8) as pool:
-            futures = [pool.submit(self._exec_tool, tc) for tc in tool_calls]
-            return [f.result() for f in futures]
+            futures = {
+                i: pool.submit(self._exec_tool, tc)
+                for i, tc in enumerate(tool_calls)
+                if results[i] is None
+            }
+            for i, future in futures.items():
+                results[i] = future.result()
+        return results
 
     def _answer_pending_tool_calls(self, tool_calls):
         """Backfill a tool reply for every call that didn't get one.

{corecoder-0.4.2 → corecoder-0.5.0}/corecoder/cli.py

@@ -15,6 +15,7 @@ from . import __version__
 from .agent import Agent
 from .config import Config
 from .llm import LLM, LiteLLM
+from .permissions import Permission
 from .session import list_sessions, load_session, save_session
 
 console = Console()
@@ -29,6 +30,7 @@ def _parse_args():
     p.add_argument("--base-url", help="API base URL (default: $OPENAI_BASE_URL)")
     p.add_argument("--api-key", help="API key (default: $OPENAI_API_KEY)")
     p.add_argument("-p", "--prompt", help="One-shot prompt (non-interactive mode)")
+    p.add_argument("--yes", action="store_true", help="Auto-approve every tool call (for scripts and CI)")
     p.add_argument("--demo", action="store_true", help="Run the offline scripted demo (no API key needed)")
     p.add_argument("-r", "--resume", metavar="ID", help="Resume a saved session")
     p.add_argument("-v", "--version", action="version", version=f"%(prog)s {__version__}")
@@ -76,7 +78,14 @@ def main():
         temperature=config.temperature,
         max_tokens=config.max_tokens,
     )
-    agent = Agent(llm=llm, max_context_tokens=config.max_context_tokens)
+    # consent layer: ask in the REPL, refuse in one-shot mode, --yes skips it
+    if args.yes:
+        permission = Permission(allow_all=True)
+    elif args.prompt:
+        permission = Permission()
+    else:
+        permission = Permission(ask=_ask_permission)
+    agent = Agent(llm=llm, max_context_tokens=config.max_context_tokens, permission=permission)
 
     # resume saved session
     if args.resume:
@@ -101,8 +110,27 @@ def main():
     _repl(agent, config)
 
 
+def _ask_permission(tool_name: str, arguments: dict) -> str:
+    """REPL consent prompt. Anything but a clear yes counts as a no."""
+    console.print(f"\n[bold yellow]permission requested:[/] [cyan]{tool_name}[/cyan]({_brief(arguments)})")
+    try:
+        answer = pt_prompt("  [y] allow once  [a] always allow this tool  [n] deny: ").strip().lower()
+    except (EOFError, KeyboardInterrupt):
+        console.print("[dim]denied[/dim]")
+        return "deny"
+    if answer in ("y", "yes"):
+        return "once"
+    if answer in ("a", "always"):
+        return "always"
+    return "deny"
+
+
 def _run_once(agent: Agent, prompt: str):
     """Non-interactive: run one prompt and exit."""
+    perm = getattr(agent, "permission", None)
+    if perm is not None and perm.ask is None and not perm.allow_all:
+        console.print("[dim]one-shot mode: mutating tools are refused unless you pass --yes[/dim]")
+
     def on_token(tok):
         print(tok, end="", flush=True)
 
@@ -123,10 +151,13 @@ def _run_once(agent: Agent, prompt: str):
 
 def _repl(agent: Agent, config: Config):
     """Interactive read-eval-print loop."""
+    perm = getattr(agent, "permission", None)
+    mode = "auto-approve every tool call (--yes)" if (perm and perm.allow_all) else "ask before mutating tools"
     console.print(Panel(
         f"[bold]CoreCoder[/bold] v{__version__}\n"
         f"Model: [cyan]{config.model}[/cyan]"
         + (f"  Base: [dim]{config.base_url}[/dim]" if config.base_url else "")
+        + f"\nPermissions: [cyan]{mode}[/cyan]"
         + "\nType [bold]/help[/bold] for commands, [bold]Ctrl+C[/bold] to cancel, [bold]quit[/bold] to exit.",
         border_style="blue",
     ))

corecoder-0.5.0/corecoder/permissions.py

@@ -0,0 +1,48 @@
+"""User consent for tool calls, distilled from Claude Code's permissions.
+
+The tools split in two. Read-only ones (read_file, glob, grep, todo_write)
+run the moment the model asks; the mutating ones (edit_file, write_file,
+bash, and spawning a sub-agent) stop for a yes first. "Always allow" is
+remembered per tool for the rest of the session: per tool rather than per
+command, because one approved bash prefix says nothing about the next
+command anyway.
+
+When there is nobody to ask (one-shot -p mode, or a library embedding with
+no callback), a mutating call is refused instead of blocking on input that
+can never arrive. The refusal travels back as an ordinary tool result, so
+the loop survives and the model can route around it.
+"""
+
+
+class Permission:
+    """Session-scoped consent state. Pure: no I/O, the CLI hands in `ask`."""
+
+    READ_ONLY = frozenset({"read_file", "glob", "grep", "todo_write"})
+
+    def __init__(self, ask=None, allow_all: bool = False):
+        # ask(tool_name, arguments) -> "once" | "always" | "deny"
+        self.ask = ask
+        self.allow_all = allow_all
+        self._always: set[str] = set()
+
+    def check(self, tool_name: str, arguments: dict) -> str | None:
+        """Decide one call. None lets it through; a string is the refusal
+        the model receives as its tool result."""
+        if tool_name in self.READ_ONLY or self.allow_all or tool_name in self._always:
+            return None
+        if self.ask is None:
+            return (
+                f"Permission denied: {tool_name} mutates state and this session is "
+                "non-interactive, so nobody can approve it. Rerun with --yes, or "
+                "tell the user the exact step so they can run it themselves."
+            )
+        verdict = self.ask(tool_name, arguments)
+        if verdict == "always":
+            self._always.add(tool_name)
+            return None
+        if verdict == "once":
+            return None
+        return (
+            f"Permission denied: the user refused this {tool_name} call. "
+            "Do not retry it unchanged; ask what they would prefer instead."
+        )

{corecoder-0.4.2 → corecoder-0.5.0}/corecoder/tools/agent.py

@@ -48,6 +48,8 @@ class AgentTool(Tool):
             tools=[t for t in parent.tools if t.name != "agent"],  # no recursive agents
             max_context_tokens=parent.context.max_tokens,
             max_rounds=20,
+            # the sub-agent answers to the same consent layer as the parent
+            permission=parent.permission,
         )
 
         # a sub-agent failure comes back as text, never propagates into the parent

{corecoder-0.4.2 → corecoder-0.5.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "corecoder"
-version = "0.4.2"
+version = "0.5.0"
 description = "Minimal AI coding agent (~1,000 lines of Python) inspired by Claude Code. Works with any LLM. (formerly NanoCoder)"
 readme = "README.md"
 license = "MIT"

corecoder-0.5.0/tests/test_permissions.py

@@ -0,0 +1,181 @@
+"""Consent gating for mutating tools: the Permission layer and its wiring."""
+
+from corecoder import Agent
+from corecoder.llm import LLMResponse, ScriptedLLM, ToolCall
+from corecoder.permissions import Permission
+from corecoder.tools import get_tool
+from corecoder.tools.agent import AgentTool
+from corecoder.tools.write import WriteFileTool
+
+
+def _write_call(call_id, path):
+    return ToolCall(id=call_id, name="write_file",
+                    arguments={"file_path": str(path), "content": "x\n"})
+
+
+def _two_writes_then_text(tmp_path):
+    return [
+        LLMResponse(tool_calls=[_write_call("c1", tmp_path / "a.txt")]),
+        LLMResponse(tool_calls=[_write_call("c2", tmp_path / "b.txt")]),
+        LLMResponse(content="done"),
+    ]
+
+
+def test_read_only_tools_run_without_consent(tmp_path):
+    f = tmp_path / "note.txt"
+    f.write_text("hello", encoding="utf-8")
+    agent = Agent(
+        llm=ScriptedLLM([
+            LLMResponse(tool_calls=[ToolCall(id="c1", name="read_file", arguments={"file_path": str(f)})]),
+            LLMResponse(content="read it"),
+        ]),
+        tools=[get_tool("read_file")],
+        permission=Permission(),  # nobody to ask, and it doesn't matter
+    )
+
+    assert agent.chat("go") == "read it"
+    assert "hello" in agent.messages[2]["content"]
+
+
+def test_allow_once_asks_again_for_the_next_call(tmp_path):
+    asked = []
+    agent = Agent(
+        llm=ScriptedLLM(_two_writes_then_text(tmp_path)),
+        tools=[WriteFileTool()],
+        permission=Permission(ask=lambda name, args: asked.append(name) or "once"),
+    )
+
+    assert agent.chat("go") == "done"
+    assert asked == ["write_file", "write_file"]  # every call asks
+    assert (tmp_path / "a.txt").exists() and (tmp_path / "b.txt").exists()
+
+
+def test_always_allow_is_remembered_for_the_session(tmp_path):
+    asked = []
+    agent = Agent(
+        llm=ScriptedLLM(_two_writes_then_text(tmp_path)),
+        tools=[WriteFileTool()],
+        permission=Permission(ask=lambda name, args: asked.append(name) or "always"),
+    )
+
+    assert agent.chat("go") == "done"
+    assert asked == ["write_file"]  # the second call went straight through
+    assert (tmp_path / "a.txt").exists() and (tmp_path / "b.txt").exists()
+
+
+def test_deny_skips_execution_and_reports_back(tmp_path):
+    agent = Agent(
+        llm=ScriptedLLM([
+            LLMResponse(tool_calls=[_write_call("c1", tmp_path / "a.txt")]),
+            LLMResponse(content="understood"),
+        ]),
+        tools=[WriteFileTool()],
+        permission=Permission(ask=lambda name, args: "deny"),
+    )
+
+    assert agent.chat("go") == "understood"  # the loop survived the refusal
+    assert not (tmp_path / "a.txt").exists()
+    refusal = agent.messages[2]
+    assert refusal["role"] == "tool" and refusal["tool_call_id"] == "c1"
+    assert "Permission denied" in refusal["content"]
+
+
+def test_no_callback_means_auto_deny(tmp_path):
+    # one-shot -p mode wires Permission() with no ask: refuse, never hang
+    agent = Agent(
+        llm=ScriptedLLM([
+            LLMResponse(tool_calls=[_write_call("c1", tmp_path / "a.txt")]),
+            LLMResponse(content="ok"),
+        ]),
+        tools=[WriteFileTool()],
+        permission=Permission(),
+    )
+
+    assert agent.chat("go") == "ok"
+    assert not (tmp_path / "a.txt").exists()
+    assert "non-interactive" in agent.messages[2]["content"]
+
+
+def test_allow_all_approves_without_any_callback(tmp_path):
+    # what --yes wires in
+    agent = Agent(
+        llm=ScriptedLLM(_two_writes_then_text(tmp_path)),
+        tools=[WriteFileTool()],
+        permission=Permission(allow_all=True),
+    )
+
+    assert agent.chat("go") == "done"
+    assert (tmp_path / "a.txt").exists() and (tmp_path / "b.txt").exists()
+
+
+def test_parallel_calls_each_get_their_own_decision(tmp_path):
+    marker = tmp_path / "touched"
+    calls = [
+        ToolCall(id="c1", name="bash", arguments={"command": f"touch {marker}"}),
+        _write_call("c2", tmp_path / "ok.txt"),
+    ]
+    agent = Agent(
+        llm=ScriptedLLM([LLMResponse(tool_calls=calls), LLMResponse(content="done")]),
+        tools=[get_tool("bash"), WriteFileTool()],
+        permission=Permission(ask=lambda name, args: "deny" if name == "bash" else "once"),
+    )
+
+    assert agent.chat("go") == "done"
+    assert not marker.exists()              # the denied bash never ran
+    assert (tmp_path / "ok.txt").exists()   # the allowed write did
+    results = {m["tool_call_id"]: m["content"] for m in agent.messages if m.get("role") == "tool"}
+    assert "Permission denied" in results["c1"]
+    assert results["c2"].startswith("Wrote")
+
+
+def test_sub_agent_inherits_the_permission_layer(tmp_path):
+    seen = []
+
+    def ask(name, args):
+        seen.append(name)
+        return "once" if name == "agent" else "deny"
+
+    target = tmp_path / "sub.txt"
+    agent = Agent(
+        llm=ScriptedLLM([
+            LLMResponse(tool_calls=[ToolCall(id="c1", name="agent", arguments={"task": "write the file"})]),
+            LLMResponse(tool_calls=[_write_call("c2", target)]),  # the sub-agent's move
+            LLMResponse(content="could not write"),               # the sub-agent's reply
+            LLMResponse(content="parent done"),
+        ]),
+        tools=[AgentTool(), WriteFileTool()],
+        permission=Permission(ask=ask),
+    )
+
+    assert agent.chat("go") == "parent done"
+    assert seen == ["agent", "write_file"]  # consent followed into the sub-agent
+    assert not target.exists()
+
+
+# --- the CLI side of the layer ---
+
+def test_yes_flag_parses(monkeypatch):
+    from corecoder.cli import _parse_args
+    monkeypatch.setattr("sys.argv", ["corecoder", "--yes"])
+    assert _parse_args().yes
+
+
+def test_ask_prompt_maps_answers(monkeypatch):
+    from corecoder import cli
+    answers = iter(["y", "a", "n", "garbage"])
+    monkeypatch.setattr(cli, "pt_prompt", lambda *a, **k: next(answers))
+
+    assert cli._ask_permission("bash", {"command": "ls"}) == "once"
+    assert cli._ask_permission("bash", {}) == "always"
+    assert cli._ask_permission("bash", {}) == "deny"
+    assert cli._ask_permission("bash", {}) == "deny"  # junk input is a no
+
+
+def test_ask_prompt_eof_denies(monkeypatch):
+    from corecoder import cli
+
+    def eof(*a, **k):
+        raise EOFError
+
+    monkeypatch.setattr(cli, "pt_prompt", eof)
+    assert cli._ask_permission("bash", {}) == "deny"