kolega-code 0.3.1__tar.gz → 0.4.0__tar.gz

{kolega_code-0.3.1 → kolega_code-0.4.0}/.gitignore

@@ -7,6 +7,7 @@ __pycache__/
 .env
 .env.*
 !.env.example
+.kolega/permissions.json
 dist/
 build/
 *.egg-info/

{kolega_code-0.3.1 → kolega_code-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kolega-code
-Version: 0.3.1
+Version: 0.4.0
 Summary: Local-first AI coding agent for the terminal
 Project-URL: Homepage, https://kolega-ai.github.io/kolega-code/
 Project-URL: Documentation, https://kolega-ai.github.io/kolega-code/

{kolega_code-0.3.1 → kolega_code-0.4.0}/RELEASING.md

@@ -6,38 +6,54 @@ version should also have a GitHub Release for its matching tag.
 
 ## Release process
 
-1. Confirm `pyproject.toml`, `uv.lock`, and package `__version__` values have
-   the release version.
+Release version bumps must happen in a pull request. Do not tag an unmerged
+release branch.
 
-2. Run the fast test suite:
+1. Create a release branch from the latest `main`:
+
+   ```bash
+   git checkout main
+   git pull origin main
+   git checkout -b chore/release-v0.3.2
+   ```
+
+2. Update `pyproject.toml`, `uv.lock`, and package `__version__` values to the
+   release version.
+
+3. Run the fast test suite:
 
    ```bash
    uv run pytest -ra --durations=50 --import-mode=importlib -m "not slow"
    ```
 
-3. Commit the release bump:
+4. Commit the release bump and open a pull request against `main`:
 
    ```bash
-   git commit -m "chore: release v0.3.0"
+   git commit -m "chore: release v0.3.2"
+   git push -u origin chore/release-v0.3.2
    ```
 
-4. Create and push a matching tag:
+   The PR must be reviewed, pass CI, and be merged before tagging.
+
+5. After the PR is merged, update local `main`, then create and push a matching
+   tag from the merge commit:
 
    ```bash
-   git tag v0.3.0
-   git push origin main
-   git push origin v0.3.0
+   git checkout main
+   git pull origin main
+   git tag v0.3.2
+   git push origin v0.3.2
    ```
 
-5. Confirm the `Release` GitHub Actions workflow completes. It builds and tests
+6. Confirm the `Release` GitHub Actions workflow completes. It builds and tests
    the package, publishes to PyPI, then creates the GitHub Release.
 
-6. Verify the release:
+7. Verify the release:
 
    ```bash
    uv tool install --force kolega-code
    kolega-code --version
-   gh release view v0.3.0 --repo kolega-ai/kolega-code
+   gh release view v0.3.2 --repo kolega-ai/kolega-code
    ```
 
 The GitHub Release uses PyPI as the canonical package distribution and keeps

{kolega_code-0.3.1 → kolega_code-0.4.0}/docs/astro.config.mjs

@@ -89,6 +89,10 @@ export default defineConfig({
           label: "Skills",
           items: [{ label: "Agent Skills", slug: "skills" }],
         },
+        {
+          label: "Hooks",
+          items: [{ label: "Lifecycle Hooks", slug: "hooks" }],
+        },
         {
           label: "How It Works",
           items: [

{kolega_code-0.3.1 → kolega_code-0.4.0}/docs/src/content/docs/cli/ask.md

@@ -20,6 +20,7 @@ kolega-code ask "<prompt>" [options]
 | `--save` | Persist the session after the prompt completes |
 | `--json` | Emit response chunks and events as JSON |
 | `--browser-visible` | Launch visible Playwright browser windows |
+| `--permission-mode <auto\|ask>` | Shell/edit permission mode (default `auto`) |
 | `--session <ID>` | Resume or create a specific session |
 | `--state-dir <PATH>` | Directory for CLI session state |
 
@@ -97,3 +98,10 @@ The stream includes:
 In plain (non-JSON) mode, the answer is written to **stdout** while sub-agent and
 tool activity is reported on **stderr** — so piping stdout gives you just the
 answer.
+
+## Permissions
+
+`ask` defaults to `--permission-mode auto` so scripts do not stop for
+confirmations. If you pass `--permission-mode ask`, shell commands and file edits
+prompt on stderr when stdin is interactive. Persisted allow rules are stored in
+the project at `.kolega/permissions.json`.

{kolega_code-0.3.1 → kolega_code-0.4.0}/docs/src/content/docs/cli/overview.md

@@ -39,6 +39,7 @@ kolega-code [PROJECT_PATH]
 | `--new` | Start a new session (this is the default) |
 | `--resume [THREAD_ID]` | Resume the latest saved thread, or a specific thread/session ID |
 | `--browser-visible` | Launch visible Playwright browser windows instead of headless |
+| `--permission-mode <auto\|ask>` | Shell/edit permission mode. TUI sessions default to `ask` |
 | `--session <ID>` | Legacy alias for `--resume THREAD_ID` |
 
 See [Sessions & Resuming](../../tui/sessions-and-resume/) for the full session

{kolega_code-0.3.1 → kolega_code-0.4.0}/docs/src/content/docs/concepts/agents.md

@@ -27,9 +27,12 @@ findings. The available dispatch targets include:
 - `dispatch_coding_agent` — hand off a self-contained coding task.
 - `dispatch_general_agent` — a general-purpose helper.
 
-Sub-agent activity is reported live: in the TUI you'll see it in the conversation
-and the **Logs** tab; with `ask` it surfaces as events (on stderr in plain mode, or
-as `event` objects with `--json`).
+Sub-agent activity is reported live. In the TUI each sub-agent gets a live card in
+the conversation, and pressing `Ctrl+G` opens the
+[sub-agent inspector](../../tui/interface/#sub-agent-inspector) — a full-screen view
+of every sub-agent's complete trajectory: its thinking, tool calls, and results.
+Lifecycle events also appear in the **Logs** tab. With `ask`, sub-agent activity
+surfaces as events (on stderr in plain mode, or as `event` objects with `--json`).
 
 ## Modes vs. agents
 

{kolega_code-0.3.1 → kolega_code-0.4.0}/docs/src/content/docs/concepts/tools.md

@@ -62,3 +62,7 @@ files and running commands require Build mode's full toolset.
 
 This separation is what makes Plan mode safe to run against any codebase: the
 planning agent can look but not touch.
+
+In the Textual TUI, Build mode defaults to `ask` permission mode. Shell commands
+and file edits must be approved before they run unless you switch to `auto` or
+save a matching allow rule in `.kolega/permissions.json`.

kolega_code-0.4.0/docs/src/content/docs/hooks.md

@@ -0,0 +1,247 @@
+---
+title: Hooks
+description: Run shell commands, Python callables, or LLM checks on agent lifecycle events to observe, block, or modify what the agent does.
+---
+
+**Hooks** let you attach handlers to the agent's **lifecycle events** — points like
+"before a tool runs", "a prompt was submitted", or "the agent is about to stop". A hook
+can **observe** (log, notify), **block** (deny a tool, end a turn, keep the agent
+working), or **modify** (rewrite a tool's input or output, inject context).
+
+This is how you add guardrails ("never run `rm -rf`"), automation ("format files after
+every edit"), and quality gates ("don't stop until the tests pass") without changing the
+agent itself.
+
+## Where hooks live
+
+Hooks are declared in JSON, in two places that are **merged** (global first, project last):
+
+- **Global / user:** `hooks.json` in the Kolega Code state directory — always active. The
+  state directory is platform-specific:
+  - macOS: `~/Library/Application Support/kolega-code/hooks.json`
+  - Linux: `$XDG_STATE_HOME/kolega-code/hooks.json` (defaults to `~/.local/state/kolega-code/hooks.json`)
+  - Windows: `%LOCALAPPDATA%\kolega-code\hooks.json`
+
+  Override the location with the `KOLEGA_CODE_STATE_DIR` environment variable or the
+  `--state-dir <dir>` flag (the file is then `<dir>/hooks.json`).
+- **Project:** `<project>/.kolega/hooks.json` — alongside `permissions.json`. Because a
+  project file can run arbitrary commands from a cloned repo, project hooks are
+  **disabled until you trust the project** (see [Trust](#trusting-project-hooks)).
+
+Both files use the same shape:
+
+```json
+{
+  "schema_version": 1,
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "execute_terminal_command|run_command_tracked",
+        "hooks": [
+          { "type": "command", "command": "./.kolega/guard-bash.sh", "timeout": 30 }
+        ]
+      }
+    ]
+  }
+}
+```
+
+- The `hooks` map is keyed by **event name**.
+- Each entry has a **`matcher`** and a list of **hook handlers**.
+- `matcher` is tested against the tool name for tool events (or a source string for other
+  events): `""` or `"*"` matches everything; `"Edit|Write"` is an exact-name OR list;
+  anything else is a regular expression (e.g. `"mcp__.*"`).
+- Handler lists from the global and project files are concatenated, so the global handler
+  sees the action first and the project handler last.
+
+## Lifecycle events
+
+| Event | When it fires | What a "block" does |
+|---|---|---|
+| `SessionStart` | The agent session begins | Advisory; can inject starting context |
+| `UserPromptSubmit` | You submit a prompt, before the agent sees it | Ends the turn; the reason is shown as a warning |
+| `PreToolUse` | Before a tool runs (after the permission gate) | Denies the tool; the reason is returned to the agent as a tool error, so it can adjust |
+| `PostToolUse` | After a tool succeeds (and on failure) | Ends the turn; the reason is shown as a warning |
+| `PreCompact` | Before the conversation is compacted | Advisory |
+| `Stop` | The agent is about to finish its turn | Keeps the agent working; the reason becomes its next instruction |
+| `SubagentStop` | A dispatched sub-agent finished | Advisory; can annotate the result the parent sees |
+| `Notification` | A permission prompt is about to be shown | Advisory (desktop notifications, sounds) |
+| `SessionEnd` | The session ends | Advisory (cleanup, final logging) |
+
+Hooks can also **modify** rather than block:
+
+- `PreToolUse` can return `updatedInput` to rewrite the tool's arguments.
+- `PostToolUse` can return `updatedToolOutput` to replace what the model sees, or
+  `additionalContext` to append to it.
+- `SessionStart` / `UserPromptSubmit` can return `additionalContext` to inject text.
+
+## Hook types
+
+### `command` — run a shell program
+
+The event is sent as JSON on **stdin**. The hook communicates back through its exit code:
+
+- **exit 0** — success. Optional JSON on stdout controls behavior:
+  ```json
+  {
+    "hookSpecificOutput": {
+      "permissionDecision": "deny",
+      "permissionDecisionReason": "rm -rf is not allowed here",
+      "updatedInput": { "command": "ls" },
+      "updatedToolOutput": "…",
+      "additionalContext": "…"
+    },
+    "systemMessage": "shown to the user",
+    "continue": false
+  }
+  ```
+- **exit 2** — block. Whatever the hook wrote to **stderr** becomes the reason.
+- **any other code** — a non-blocking error: it is logged and the action proceeds.
+
+```json
+{ "type": "command", "command": "./.kolega/format.sh", "timeout": 30 }
+```
+
+Commands run with the project directory as the working directory and are split like a
+shell argument list (no shell features such as pipes — call a script if you need them).
+
+### `python` — run an in-process callable
+
+Point at an importable `module.path:function`. It receives a `LifecycleEvent` and returns
+a `HookOutcome` (or a dict with the same fields). Runs in the agent's process — best for
+first-party checks.
+
+```json
+{ "type": "python", "callable": "myproject.hooks:block_secrets", "timeout": 15 }
+```
+
+```python
+from kolega_code.hooks import HookOutcome
+
+def block_secrets(event):
+    inputs = event.payload.get("tool_input", {})
+    if "AWS_SECRET" in str(inputs):
+        return HookOutcome.deny("Refusing to write a secret to disk.")
+    return HookOutcome.empty()
+```
+
+### `prompt` and `agent` — let an LLM decide
+
+For judgment calls rather than deterministic rules. Both return a yes/no decision as
+`{"ok": true}` (allow) or `{"ok": false, "reason": "…"}` (block); the per-event meaning of
+a block is the same as the table above.
+
+- **`prompt`** sends your prompt plus the event data to a model (the fast model by
+  default; `"model"` may be `"fast"`, `"long"`, or `"thinking"`). Use `$EVENT` in the
+  prompt to interpolate the event JSON.
+
+  ```json
+  {
+    "type": "prompt",
+    "prompt": "Have all of the user's requested tasks been completed? $EVENT",
+    "model": "fast",
+    "timeout": 30
+  }
+  ```
+
+- **`agent`** spawns a full sub-agent that can read files, search the code, and run
+  commands to verify a condition before answering. Heavier, with a longer default timeout.
+  Because an agent hook uses tools, it is **not allowed on `PreToolUse`/`PostToolUse`**
+  (that would recurse); use it on `Stop`, `SubagentStop`, `UserPromptSubmit`, or the
+  session events.
+
+  ```json
+  {
+    "type": "agent",
+    "prompt": "Run the test suite. Only report ok:true if every test passes.",
+    "timeout": 120
+  }
+  ```
+
+  Tool calls made by an agent hook do **not** re-trigger tool hooks, so there is no
+  infinite loop.
+
+## Examples
+
+**Block dangerous shell commands (project, command hook):**
+
+```json
+{
+  "schema_version": 1,
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "execute_terminal_command|run_command|run_command_tracked",
+        "hooks": [{ "type": "command", "command": "./.kolega/deny-rm.sh" }]
+      }
+    ]
+  }
+}
+```
+
+**Don't stop until the tests pass (prompt hook):**
+
+```json
+{
+  "schema_version": 1,
+  "hooks": {
+    "Stop": [
+      {
+        "matcher": "*",
+        "hooks": [{
+          "type": "prompt",
+          "prompt": "Based on the conversation, did the agent finish ALL requested work AND leave the tests passing? $EVENT"
+        }]
+      }
+    ]
+  }
+}
+```
+
+**Verify tests actually pass before stopping (agent hook):**
+
+```json
+{
+  "schema_version": 1,
+  "hooks": {
+    "Stop": [
+      {
+        "matcher": "*",
+        "hooks": [{
+          "type": "agent",
+          "prompt": "Run the project's test command and confirm it exits cleanly.",
+          "timeout": 120
+        }]
+      }
+    ]
+  }
+}
+```
+
+## Trusting project hooks
+
+A project's `.kolega/hooks.json` can run arbitrary commands, so it is **ignored until you
+explicitly trust the project**. Global/user hooks are always trusted.
+
+When an untrusted project defines hooks, Kolega Code tells you and runs only the global
+hooks. To enable the project's hooks, launch with:
+
+```bash
+kolega-code --trust-hooks          # TUI
+kolega-code ask "…" --trust-hooks  # non-interactive
+```
+
+Trust is recorded once (per resolved project path) in your user settings, so future runs
+in that project enable its hooks automatically.
+
+## Safety and behavior notes
+
+- **Failure is isolated.** A hook that crashes, times out, or prints garbage is logged and
+  the action proceeds — a broken hook never wedges the agent. Only a clean `exit 2`,
+  `permissionDecision: "deny"`, or `ok: false` blocks.
+- **Each handler has a `timeout`** (seconds). On timeout the process is killed and treated
+  as a non-blocking error.
+- **Tool hooks apply to sub-agents too**, so a `PreToolUse` guard also covers tools used by
+  dispatched sub-agents.
+- A `Stop` hook can force the agent to keep working only a bounded number of times per
+  turn, so a misbehaving "don't stop" hook cannot loop forever.

{kolega_code-0.3.1 → kolega_code-0.4.0}/docs/src/content/docs/tui/interface.md

@@ -15,7 +15,7 @@ The screen is split into two columns:
   stream in live, tool calls and sub-agent activity appear inline, and detailed
   tool results are collapsed by default so you can expand only what you need.
 - **Side panel** (right) — a set of tabs for status, logs, the terminal, planning,
-  and settings.
+  and settings. Toggle it with `Ctrl+O` or `/sidebar`.
 
 At the bottom sits the **composer** — the text box where you type prompts. See
 [Chat Composer](../composer/) for everything it can do.
@@ -24,7 +24,7 @@ At the bottom sits the **composer** — the text box where you type prompts. See
 
 | Tab | What it shows |
 | --- | --- |
-| **Status** | The active provider/model and thinking effort, the current interaction mode (Build/Plan), the agent's turn state (idle, generating, thinking, running a tool, running sub-agents, waiting for input, …), token usage, and context warnings. |
+| **Status** | The active provider/model and thinking effort, the current interaction mode (Build/Plan), permission mode, the agent's turn state (idle, generating, thinking, running a tool, running sub-agents, waiting for input, …), token usage, and context warnings. |
 | **Logs** | A timestamped, color-coded activity log: sub-agent lifecycle, tool calls, configuration changes. An indicator flags new entries when you're on another tab. |
 | **Terminal** | Live output from commands the agent runs. |
 | **Planning** | The current **Plan** (markdown from the planning agent) and the shared **Task List** that both modes can edit. |
@@ -37,18 +37,49 @@ At the bottom sits the **composer** — the text box where you type prompts. See
   can return to the live edge.
 - **Tool results** — shown as collapsible blocks with a state indicator
   (running / done / failed). Expand to see the full result.
-- **Sub-agents** — when the main agent dispatches a sub-agent, its activity is
-  tracked live with status updates.
+- **Sub-agents** — when the main agent dispatches a sub-agent, a live card tracks
+  it inline: the agent name, elapsed time, tool count, token usage, what it's doing
+  right now, and a tail of its latest output. Press `Ctrl+G` (or click the card) to
+  open the full [sub-agent inspector](#sub-agent-inspector).
 - **Option lists** — when the agent asks you to choose between options (including
-  plan decisions), they render as a **vertical, arrow-key-selectable list**.
+  plan decisions and tool approvals), they render as a **vertical,
+  arrow-key-selectable list**.
   Use the arrow keys to highlight, number keys (`1`–`9`) to jump, and `Enter` to
   confirm.
 
+## Sub-agent inspector
+
+The inline cards summarize sub-agent activity; the **inspector** shows the whole
+story. Press `Ctrl+G` (or click any sub-agent card) to open a full-screen
+"mission control" view:
+
+- **Roster** (left) — every sub-agent dispatched this turn, running or finished,
+  each with a live spinner, status, elapsed time, tool count, and token usage.
+  Nested sub-agents are indented by depth.
+- **Trajectory** (right) — the selected agent's full run: its thinking, each tool
+  call, the tool results (expandable, just like the main transcript), and its
+  responses, streaming live as it works.
+
+| Keys | Action |
+| --- | --- |
+| `Ctrl+G` | Open the inspector (on the most recently active sub-agent) |
+| `↑` / `↓` | Switch between sub-agents |
+| `Tab` then `Enter` | Focus a tool call and expand it (or click it) |
+| `o` | Toggle follow — auto-scroll to the newest activity |
+| `y` | Copy the selected agent's trajectory to the clipboard |
+| `Esc` / `q` | Close the inspector |
+
+The inspector is read-only: opening or closing it never interrupts the agent, so
+the turn keeps running while you look around.
+
 ## Key bindings at a glance
 
 | Keys | Action |
 | --- | --- |
 | `Shift+Tab` | Toggle Build ⇄ Plan mode |
+| `Ctrl+P` | Toggle shell/edit permissions between Ask ⇄ Auto |
+| `Ctrl+O` | Show or hide the side panel |
+| `Ctrl+G` | Open the sub-agent inspector |
 | `Enter` | Send the prompt |
 | `Shift+Enter` / `Ctrl+J` | Insert a newline |
 | `Ctrl+C` / `Escape` | Cancel the current generation |

{kolega_code-0.3.1 → kolega_code-0.4.0}/docs/src/content/docs/tui/modes.md

@@ -14,6 +14,14 @@ implementing whatever you ask.
 
 Use Build mode for hands-on work: making changes, running tests, fixing bugs.
 
+Build mode is still subject to the current **permission mode**. TUI sessions
+default to `ask`, so shell commands and file edits prompt before they run. Press
+`Ctrl+P` to toggle between `ask` and `auto`, or use `/permissions ask`,
+`/permissions auto`, and `/permissions toggle`.
+
+When you choose an “always allow” approval, Kolega Code stores the local rule in
+`.kolega/permissions.json` for that project.
+
 ## Plan mode
 
 A **read-only** planning pass. Plan mode uses a standalone planning agent that does

{kolega_code-0.3.1 → kolega_code-0.4.0}/docs/src/content/docs/tui/slash-commands.md

@@ -33,8 +33,11 @@ These control the app and your session.
 | Command | Description |
 | --- | --- |
 | `/skills` | List available Agent Skills |
+| `/init` | Create or update `AGENTS.md` for this repository |
 | `/plan` | Switch to [Plan mode](../modes/) |
 | `/build` | Switch to [Build mode](../modes/) |
+| `/sidebar` | Show or hide the side panel |
+| `/permissions` | Show or switch the shell/edit permission mode |
 | `/model` | Choose the active model |
 | `/effort` | Choose the active model's thinking effort |
 | `/copy` | Copy the last response to the clipboard |
@@ -49,6 +52,14 @@ provider. You can also switch directly with `/model <name>`.
 Run `/effort` to open a selectable list of supported effort values for the
 active model. You can also switch directly with `/effort <level>`.
 
+Run `/init` to have the agent inspect the repository and create or update a
+concise root `AGENTS.md`. Extra text after the command is passed as focus or
+constraints:
+
+```text
+/init focus on Python packaging and test commands
+```
+
 ## Skills
 
 Any [skill](../../skills/) discovered in `.agents/skills/` is available as

{kolega_code-0.3.1 → kolega_code-0.4.0}/kolega_code/__init__.py

@@ -148,4 +148,4 @@ __all__ = [
     "parse_git_status_output",
 ]
 
-__version__ = "0.3.1"
+__version__ = "0.4.0"

{kolega_code-0.3.1 → kolega_code-0.4.0}/kolega_code/agent/__init__.py

@@ -39,4 +39,4 @@ __all__ = [
     "ToolExtension",
 ]
 
-__version__ = "0.3.1"
+__version__ = "0.4.0"