Skip to content
Skills Library
AI & agents · Automation

agent-session-control

/agent-session-control

Run locally owned coding-agent sessions with the agent-session-control CLI: plan or host a session, submit one prompt turn, and observe the run. Use for local session control; not a task scheduler, planner, or permission bypass.

Author
x0c ↗
Licence
MIT
Last repository change
02.11.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
2
Scripts
0
HTML comments
0
URLs in SKILL.md
4
Deprecation

No signals detected. Repository changed on 02.11.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Run locally owned coding-agent sessions with the agent-session-control CLI: plan or host a session, submit one prompt turn, and observe the run. Use for local session control; not a task scheduler, planner, or permission bypass.

Original author description

Run locally owned coding-agent sessions with the agent-session-control CLI: plan or host a session, submit one prompt turn, and observe the run. Use for local session control; not a task scheduler, planner, or permission bypass.

How it works

  1. 1. Probe the CLI first
  2. 2. Select runtime, model, and approvals explicitly
  3. 3. One scoped session lifecycle
  4. 4. Observe, settle, release (same scope)
  5. 5. Read outcomes from the envelope
  6. Boundaries
Original SKILL.md headings · 262 lines, 1,796 words
SKILL.md preview
---
name: agent-session-control
description: "Run locally owned coding-agent sessions with the agent-session-control CLI: plan or host a session, submit one prompt turn, and observe the run. Use for local session control; not a task scheduler, planner, or permission bypass."
---

# Agent Session Control

Control coding-agent sessions you own on this machine through the
`agent-session-control` JSON CLI. Plans are pure data; hosting, turns,
and observation share one controller. This skill is local session
control only: it does not schedule work, plan tasks, bypass approvals,
or manage other products.

## 1. Probe the CLI first

Pin one absolute CLI path and reuse it for every command in the task.
Prefer the installed entry; the module form is equivalent:

```sh
command -v agent-session-control
ABS=/path/from/above/agent-session-control
"$ABS" version --json
"$ABS" describe --json
```

Or `python -m agent_session_control` with the project interpreter.
`version` and `describe` work offline. `describe` is the live contract:
when this skill and `--help` disagree, `--help` and `describe` win.

Judge success by exit code or the `ok` field, never by non-empty
stdout. Every non-streaming command prints exactly one
`{ok, data, error, meta}` envelope on stdout; logs go to stderr.
`run events --follow` is the only streaming command and speaks JSONL.

`next_commands` in error envelopes is rendered from the serving
interpreter (`python -m agent_session_control ...`). When several
installs exist, re-issue follow-ups through your pinned `$ABS` path
instead of assuming the hint resolves to the same copy.

### If the CLI is missing

Use the fixed GitHub release below. Version 0.1.1 is also published on
[PyPI](https://pypi.org/project/agent-session-control/0.1.1/).
Do not invent URLs, do not overwrite another installed version without
explicit approval, and do not write outside the user directory without
approval. Requires Python `>=3.10,<3.15`: pick any compatible
interpreter the caller selects (`3.10`–`3.14`) and create the venv under a concrete user-directory
default or a caller-selected path — then address the CLI through that
venv only, never through the global `PATH`. Always call pip as
`python -m pip` from the venv `python` — never a bare `pip`. Pin
0.1.1: 0.1.0 is superseded (MCP secrets could reach process argv there).

```sh
PY=/path/to/python3.12          # caller-selected 3.10–3.14 interpreter
VENV=~/.local/asc-venv          # concrete default; caller may select another user-directory path
"$PY" -m venv "$VENV"
VERSION=0.1.1
BASE=https://github.com/x0c/agent-session-control/releases/download/v${VERSION}
WHEEL=${BASE}/agent_session_control-${VERSION}-py3-none-any.whl
SESSKIT=https://github.com/x0c/sesskit/releases/download/v0.2.21/sesskit-0.2.21-py3-none-any.whl
"$VENV/bin/python" -m pip install "agent-session-control @ ${WHEEL}"
"$VENV/bin/python" -m pip install "sesskit @ ${SESSKIT}" "agent-session-control[history] @ ${WHEEL}"       # native-history observation
"$VENV/bin/python" -m pip install "sesskit @ ${SESSKIT}" "agent-session-control[history,acp] @ ${WHEEL}"  # full setup with ACP adapter
```

SessKit is not on PyPI, so pip needs its fixed wheel on the command
line (`tool.uv.sources` is uv-only and is not wheel metadata). `uv`
users pin the same immutable wheel; the only authority for that URL is
the product `pyproject.toml`:

```toml
[tool.uv.sources]
sesskit = { url = "https://github.com/x0c/sesskit/releases/download/v0.2.21/sesskit-0.2.21-py3-none-any.whl" }
```

Then bind `$ABS` straight to that venv's entry and verify the
executable and its version directly — no `command -v` re-probe, no
global-`PATH` dependence:

```sh
ABS="$VENV/bin/agent-session-control"
test -x "$ABS"
"$ABS" version --json   # data: {package, version, python}; expect 0.1.1 on the venv interpreter
"$ABS" doctor --json    # read-only: interpreter, extras, runtimes, state root
```

Reinstalls converge; an existing install is not an error.

## 2. Select runtime, model, and approvals explicitly

SDK control covers five runtimes: `claude`, `codex`, `opencode`,
`cursor`, `pi`. There are no other built-ins; never guess a sixth
name. ACP serving is narrower: it requires the stdio MCP baseline, so
only `claude`, `codex`, and `opencode` can be served (`acp --runtime`
with `cursor` or `pi` is refused on stderr with exit 2 before any
protocol bytes; their SDK/CLI control is unaffected). `doctor`
reports executable presence only (`available`), never native login,
quota, or model entitlement. A missing login surfaces as an explicit
backend limit, not a pass.

- Omit `--model` to inherit the runtime default. A supplied model
  applies to that launch only and is never written anywhere.
  `opencode` has no verified per-launch model flag: `--model` there is
  refused (`model_selection_unsupported`), never silently remapped.
- Default approvals add no relaxation. Pass approval relaxation only
  when the user's explicit policy allows it for this launch; never
  auto-grant it and never write it to global or project config.
- Preview before hosting: `plan create` and `session create --dry-run`
  are pure and create no state. `--cwd` must be an absolute existing
  project directory, never `/`, the home root, Desktop, or Documents.

## 3. One scoped session lifecycle

Pick one caller-selected unique scope for the whole task and carry it
on every command — never a fixed shared path reused across tasks.
Save the exact identifiers each command returns; later steps need the
returned values, not guesses.

```sh
ROOT=$(umask 077; mktemp -d "${TMPDIR:-/tmp}/asc-task.XXXXXX")   # unique per task, owner-only
NS=demo   # stable namespace inside the scope
```

```sh
# 0. Preview (pure, no state).
"$ABS" plan create --runtime codex --cwd /tmp/proj --json

# 1. Host. Returns data.session.id, e.g. "ses_9f3a..."; save it as SES.
"$ABS" session create --runtime codex --cwd /tmp/proj --root "$ROOT" --namespace "$NS" --json

# 2. Submit one turn. Acceptance, not completion. Returns data.run.run_id; save it as RUN.
"$ABS" run submit --session-id "$SES" --prompt-file /tmp/brief.txt --request-id req-001 \
  --root "$ROOT" --namespace "$NS" --json
```

Pass exactly one of `--prompt` or `--prompt-file`; prefer
`--prompt-file PATH` with `-` for piped stdin so long briefs never
travel as argv fragments:

```sh
printf '%s\n' "continued brief" | "$ABS" run submit --session-id "$SES" --prompt-file - \
  --request-id req-002 --root "$ROOT" --namespace "$NS" --json
```

- `--request-id` is the immutable idempotency key (1-200 printable
  characters, no whitespace). Reusing the same key with the same prompt
  returns the existing run; the same key with a changed prompt is a
  `idempotency_conflict` (exit 5). Generate one stable key per prompt
  and record it; on uncertain delivery observe with `run events` /
  `run wait` instead of retrying under a new key.
- `--on-busy` is `queue` (default), `steer`, or `reject`. runtimes
  without true steering refuse `steer`; a refused steer never becomes
  a queued follow-up disguised as steering.
- Supported commands are exactly those in `describe`: `version`,
  `describe`, `doctor`, `plan create`, `plan resume`, `session create`,
  `session resume`, `session close`, `session list`, `run submit`,
  `run wait`, `run events`, `run interrupt`, `acp`. There is no
  `run status`, `run result`, or `run recover`; poll with `run events`
  and settle with `run wait`.

### MCP servers: never inline credentials

`session create` / `session resume` accept per-session stdio MCP
servers launch-only; they are never written to global or project
config and never echoed back with secret values. `--mcp-servers`
inline JSON is for entries without secrets only. Secret-bearing
configs must go through `--mcp-servers-file PATH` (`-` for piped
stdin); the two inputs are mutually exclusive. Verify the exact
spelling against `describe --command "session create"` before
running:

```sh
umask 077; set +x   # owner-only temp files from here on; never trace secret-bearing commands
CFG="$ROOT/mcp.json"   # owned temp secret config only — existing protected configs stay untouched
printf '%s\n' "$MCP_JSON" > "$CFG.tmp" && mv "$CFG.tmp" "$CFG"   # by reference, never typed
trap 'rm -f "$CFG"' EXIT   # remove only this owned temp file after the CLI returns, success or failure
"$ABS" session create --runtime codex --cwd /tmp/proj --root "$ROOT" --namespace "$NS" \
  --mcp-servers-file "$ROOT/mcp.json" --json
printf '%s\n' "$MCP_JSON" | "$ABS" session create --runtime codex --cwd /tmp/proj \
  --root "$ROOT" --namespace "$NS" --mcp-servers-file - --json
```

Prepare the file with no secret literals anywhere before the CLI:
prefer an existing protected config (it stays in place — never move
or delete it), else resolve values from the secret store or
environment by reference (`"$MCP_JSON"`, never a typed value) — no
literals in shell commands, heredocs, or `python -c`. Temp configs
and captures you create must be `0600` in the `0700` scope
(`umask 077`, xtrace off: `set +x`); remove only your owned temp
secret config in a trap after the CLI returns, success or failure —
never user configs, native histories, or control state. Never `cat`
or display a secret config; report only names, keys, and the
redacted plan. Keep secret configs and captures under `$ROOT`,
never generic `/tmp/*.json` names. Synthetic fixture values get
identical handling.

`cursor` and `pi` have no verified per-launch MCP path and refuse
servers (`unsupported`). Full entry shape, limits, and returned
fields: [per-session MCP servers](references/mcp.md).

## 4. Observe, settle, release (same scope)

```sh
"$ABS" run events --run-id "$RUN" --after 0 --root "$ROOT" --namespace "$NS" --json
"$ABS" run wait --run-id "$RUN" --timeout 120 --root "$ROOT" --namespace "$NS" --json
"$ABS" run interrupt --run-id "$RUN" --root "$ROOT" --namespace "$NS" --json
"$ABS" session close --session-id "$SES" --root "$ROOT" --namespace "$NS" --json
```

- A `wait` timeout (exit 6, `wait_timeout`) never cancels the work;
  read `run events` again to continue. `--follow` budget/timeout ends
  likewise never cancel.
- `run interrupt` only requests cancellation of exactly that run
  (`interrupt_requested`); it is confirmed when `run wait` / `run
  events` settles the run to `interrupted`. Never interrupt unrelated
  work.
- `session close` cancels owned work and releases resources but never
  deletes native history.
- `state: completed` means the turn ended; review the work before
  treating any task as done. Completion is not task acceptance.

## 5. Read outcomes from the envelope

Success: `ok: true`, `error: null`, exit 0. `data` carries
`dry_run` / `status` (`planned`, `created`, `resumed`, `submitted`,
`closed`, `interrupt_requested`), plus `session`, `run`
(`run_id`, `session_id`, `request_id`, `on_busy`), `launch`
(redacted `argv`/`env_keys`), `events` / `next_cursor` / `has_more`,
or `run` (`run_id`, `state`, `final_response`, `stop_reason`,
`error`, `evidence`). `meta` carries package/version.

Failure: `ok: false`, `data: null`, exit non-zero, with
`error: {code, message, hint, next_commands, details}`.
The ACP entry is the exception: it must keep stdout protocol-clean,
so serving refusals go to stderr as `acp: <message>` plus
`acp: hint: <hint>` with exit 2 and empty stdout.

| `error.code` | Exit | Meaning and recovery |
|---|---|---|
| `usage_error` | 2 | Fix arguments; one-step recovery via `hint` / `next_commands`. |
| `model_selection_unsupported`, `unsupported` | 2 | Refusal: unsupported runtime, model, MCP path, or ACP baseline. Do not retry with new spellings. |
| `not_found` | 3 | Exact id/path/cwd required; `session list` to locate. |
| `not_authorized` | 4 | Auth/lacks-permission; do not bypass. |
| `conflict`, `idempotency_conflict` | 5 | Same key, changed payload. Re-read the existing run; do not mint a new key to force it. |
| `wait_timeout` | 6 | Deadline passed, work continues. Observe again. |
| `uncertain_delivery` | 1 | Injection unverified. Observe via `run events` / `run wait`; never replay the write. |
| `failed` / `interrupted` / `unknown` states | 0 on `run wait` | Turn settled without success. `unknown` never masquerades as success or cancellation. |

Refusals and timeouts are informative, not retryable by rewording.
Unknown delivery never authorizes replay under any key.

## Boundaries

Never auto-grant approvals, write global or project config, grant new
MCP/database authority, or delete histories. This library controls
sessions across the five runtimes, but native conversation identity
never migrates: resume needs the exact native id/path of the same
runtime. One runtime per ACP invocation (`acp --runtime <id>`,
protocol-only stdout). Keep user content out of diagnostics; report
only ids, codes, and exits. Server setup lives in
[per-session MCP servers](references/mcp.md).

Retrospective history parsing belongs to SessKit, not to a control
turn: parsing-only questions never force-load this skill and never
submit a turn.
Files in this package (2)
  • SKILL.md 13 KB
  • references/mcp.md 4 KB

Versions

The database has no other skills named agent-session-control.

Database snapshot: 13.11.2026 · package version f500997517af (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100innoclaw-cli
    Use the local InnoClaw CLI to run app workflows and Deep Research sessions from the terminal. Trigger when the user wants command-line control over this repository instead of only using the web UI.
  • 90pb-master
    Run one control session over several Claude Code, Codex or OpenCode sessions: roster, status board, GO board, GO <session> tokens, idle notices and a handover file. Use for "master session", "supervise my sessions", "run several agents", "one control window".
  • 100session-retro
    Review a coding-agent session and turn its failures and waste into ranked fixes to the agent's environment. Use when a session went slow or wrong, after a messy agent run, or to tune CLAUDE.md or AGENTS.md.
  • 100ctxrent
    Context rent of the user's coding-agent sessions, turned into approved rules for CLAUDE.md or AGENTS.md. Use when the user runs /ctxrent, asks where their tokens or context go, why sessions are slow or expensive, or wants hygiene rules from their own session history.
  • 100coding-agent-sessions
    Finds, reads, and reconstructs coding-agent sessions across Codex, Claude, OpenCode, OMO/Senpi, and other local agent logs. Use when asked to find or search past sessions, transcripts, or subagent runs, or to recover what an earlier session did.
  • 90Linear Agents, Sessions and Coding Sessions
    This skill should be used when building, registering, or operating an agent inside Linear — agent sessions, agent activities, delegation, Agent Skills, Loops, and Linear's built-in coding sessions. Activates on "linear agent", "agent session", "agent activity", "delegate issue",…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.